The Tonder API uses standard HTTP response codes to indicate the success or failure of an API request. Your integration should be prepared to handle these codes gracefully.

​
Success Codes

Success codes indicate that your request was received and processed successfully.
CodeStatusDescription
200OKThe request was successful. Typically used for GET requests.
201CreatedThe resource was successfully created. Typically for POST requests.
202AcceptedThe request has been accepted for processing, but is not yet complete (e.g., a payment requiring 3DS).
204No ContentThe request was successful, but there is no content to return (e.g., on a DELETE request).

​
Client Error Codes

Client error codes indicate a problem with your request, such as invalid data or authentication failure. You should correct the issue in your request before retrying.
CodeStatusDescriptionAction Required
400Bad RequestThe request was improperly formatted or missing required parameters.Check the request body and parameters.
401UnauthorizedAuthentication failed. Your API key or HMAC signature is invalid.Verify your API key and signature calculation.
402Payment RequiredThe payment was declined by the processor or issuing bank.Advise the user to try a different payment method.
404Not FoundThe requested resource could not be found.Check the transaction ID or endpoint URL.
422Unprocessable EntityThe request was well-formed, but contained semantic errors (e.g., invalid email format, amount out of range).Fix the data in the specified fields.
429Too Many RequestsYou have exceeded the API rate limit.Retry the request after a delay (exponential backoff).

​
Server Error Codes

Server error codes indicate a problem with Tonder’s servers. These errors are typically temporary.
CodeStatusDescriptionAction Required
500Internal Server ErrorAn unexpected error occurred on Tonder’s servers.Retry the request after a short delay.
502Bad GatewayA dependent service is temporarily down.Retry the request after a short delay.
503Service UnavailableThe Tonder API is temporarily unavailable (e.g., for maintenance).Retry the request later. Check the status page.

​
Error Response Format

When the API returns a client or server error (4xx or 5xx), the response body will contain a JSON object with a consistent format to help you debug the issue. 
{
  "error": {
    "code": "validation_error",
    "message": "Amount must be greater than 0",
    "type": "request_error",
    "details": {
      "field": "amount",
      "received_value": -10.00
    }
  },
  "request_id": "req_abc123"
}

​
Error Object Fields

The error object contains the following fields:
FieldTypeDescription
error.codestringA specific, machine-readable code for the error.
error.messagestringA human-readable message explaining the error.
error.typestringThe category of the error (e.g., request_error, auth_error).
error.detailsobjectAdditional context about the error, such as which field failed validation.
request_idstringA unique identifier for the request. Include this ID when contacting support.

​
Next Steps

  • Test error scenarios using our testing data to make sure your integration handles unexpected responses.
  • Learn about authentication and security to avoid common authorisation errors.
  • Check the environment guide to ensure you’re using the correct URLs and credentials at each stage of development.