Error Handling

Overdrive Connect returns standardized JSON error responses for all Merchant API requests.

Every error includes a machine-readable error code, a human-readable message, and a unique request identifier to assist with troubleshooting.

Tip

Always inspect both the HTTP status code and the response body when handling API errors.

Error Response Format

Error responses are returned as JSON.

{
    "code": "PAYMENT_ALREADY_EXISTS",
    "message": "A payment with this merchant payment reference has already been completed.",
    "requestId": "3d0f71de-1e4c-4f2e-8d44-5cfbb7efaeab"
}

Field	Description
`code`	Stable machine-readable error code.
`message`	Human-readable description of the error.
`requestId`	Unique request identifier used when contacting support.

HTTP Status Codes

Status	Description
`200 OK`	Request completed successfully.
`201 Created`	Payment created successfully.
`401 Unauthorized`	Authentication failed.
`404 Not Found`	Requested resource was not found.
`409 Conflict`	Request conflicts with the current payment state.
`422 Unprocessable Entity`	Request validation failed.
`429 Too Many Requests`	Rate limit exceeded.
`500 Internal Server Error`	An unexpected server error occurred.
`502 Bad Gateway`	The payment provider returned an error.

Validation Errors

Validation failures return 422 Unprocessable Entity. Only the first validation error is returned.

{
    "code": "INVALID_AMOUNT",
    "message": "Amount is invalid.",
    "requestId": "b09356d8-1f39-447d-b4c7-9796b778d1df"
}

Common Error Codes

Error Code	HTTP	Description
`INVALID_CREDENTIALS`	401	Authentication failed.
`PAYMENT_NOT_FOUND`	404	Requested payment could not be found.
`PAYMENT_ALREADY_EXISTS`	409	The payment has already been completed.
`PAYMENT_NOT_MUTABLE`	409	The payment can no longer be modified.
`RATE_LIMIT_EXCEEDED`	429	Too many requests.
`PAYMENT_GATEWAY_ERROR`	502	The payment provider returned an error.
`INTERNAL_SERVER_ERROR`	500	An unexpected server error occurred.

Best Practice

Do not retry requests that return 401, 404, 409, or 422. These errors require correcting the request before trying again.

Requests returning 429, 500, or 502 may be retried after a short delay.

Idempotency

If you experience a timeout or lose connectivity before receiving the API response, do not immediately create a new payment.

Instead, retrieve the payment using your merchantPaymentReference to determine whether the original request was processed successfully.

Next Step

Continue to the Merchant Experience section to learn how customers interact with the hosted checkout.