The API uses conventional HTTP status codes.
| Code | Meaning |
|---|---|
| 200 | OK. Request succeeded. |
| 201 | Created. A new resource was successfully created. |
| 202 | Accepted. The request has been queued (used for refund requests). |
| 400 | Bad Request. The request body failed validation. The response body describes which fields failed and why. |
| 401 | Unauthorized. Your API key is missing, malformed, or does not match the environment. |
| 403 | Forbidden. Your API key is valid but you are not allowed to access the requested resource. |
| 404 | Not Found. The resource does not exist or does not belong to your Merchant account. |
| 429 | Too Many Requests. You've exceeded a rate limit. Back off and retry. |
| 5xx | Server error. Transient. Retry with exponential backoff; if it persists, contact support. |
Error response shape
4xx responses return a JSON body with a summary of what went wrong. For validation errors (400), expect a field-level breakdown:
{
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
"Currency": ["Currency not supported."],
"Total": ["Total is not greater then a minimum contribution for NZD"]
}
}
Recommendations
- Always handle 4xx and 5xx responses gracefully. Surface the errors detail to your own observability stack, not to end Shoppers.
- Treat 5xx responses as retryable with exponential backoff. Treat 4xx as non-retryable; fix the request.
- Include a correlation ID in your own logs so you can quickly cross-reference with Paysquad support.