Errors

The ZuriPay API uses conventional HTTP response codes and returns structured JSON error responses to help you identify and resolve issues.

Error response format

All error responses follow a consistent JSON structure with a result field set to "error" or "failed", along with an error object or message describing what went wrong.

Error object properties

Name
result
Type
string
Description
Always "error" or "failed" for error responses.
Name
error.type
Type
string
Description
A machine-readable error type identifier (e.g., Unauthorized, InvalidRequestParameters).
Name
error.message
Type
string
Description
A human-readable description of the error.
Name
message
Type
string
Description
Alternative location for the error message (some endpoints use this instead of nested error object).

Error response (structured)

{
  "result": "error",
  "error": {
    "type": "InvalidRequestParameters",
    "message": "Amount and email are required."
  }
}

Error response (simple)

{
  "result": "failed",
  "message": "Email should be more than 3 characters and less than 30 characters"
}

Error types

The following error types may be returned by the API:

Error Type	Description
`Unauthorized`	Invalid or missing API key
`InvalidRequestParameters`	Missing or invalid request body fields
`ResourceConflict`	A resource with the same identifier already exists (e.g., duplicate transaction reference)
`ResourceNotFound`	The requested resource does not exist
`RateLimitExceeded`	Too many requests -- slow down and retry
`InternalServerError`	An unexpected error occurred on the server

When you receive an error, check the error.type field first for programmatic handling, then read the error.message for human-readable details.

HTTP status codes

The ZuriPay API uses standard HTTP status codes:

Status	Description
`200`	OK -- The request was successful
`400`	Bad Request -- Invalid or missing parameters
`401`	Unauthorized -- Invalid or missing API key
`404`	Not Found -- The requested resource does not exist
`429`	Too Many Requests -- Rate limit exceeded
`500`	Internal Server Error -- Something went wrong on our end

Rate limiting

Most endpoints are rate-limited to 20 requests per minute. Authentication endpoints are limited to 5 requests per minute. When you exceed the limit, the API returns a 429 status code. Implement exponential backoff in your retry logic.

401 Unauthorized

{
  "result": "error",
  "error": {
    "type": "Unauthorized",
    "message": "Unauthorized. The provided API key is invalid."
  }
}

400 Bad Request

{
  "result": "error",
  "error": {
    "type": "InvalidRequestParameters",
    "message": "Currency is required. Parameter: currency"
  }
}