Tranzak Docs
tranzak.co Dashboard
Docs  /  API reference

Errors and rate limits

The error format of the Tranzak API, every error code with what to do about it, and how rate limits work.

Error format

Failed requests return a JSON body with success: false:

{
  "success": false,
  "error": "validation_error",
  "message": "The given data was invalid",
  "errors": {
    "amount": ["The amount field is required."],
    "currency": ["The currency must be HTG or USD."]
  }
}
Field Description
error A stable code you can branch on.
message A readable explanation. Do not show raw messages to customers unless the table says so.
errors Present on 422: the validation errors by field.

Error codes

HTTP error What to do
401 API key is required / Invalid API key Fix the key you send. Do not retry in a loop.
403 API key is not active / Website not found or inactive Reactivate the key or the website in the dashboard.
403 payment_method_not_approved Live mode only. Request access in Payment methods in the dashboard.
403 events_test_only The events feed needs a test key.
404 transaction_not_found Wrong identifier or reference, or the payment belongs to another website.
422 validation_error / invalid_cursor Fix the request. See errors.
400 payment_method_not_available The method is not enabled for this account.
400 amount_too_low / amount_too_high Change the amount. The message states the limit.
400 payment_processing_failed Show the message to the customer and offer to try again.
429 rate_limit_exceeded / too_many_attempts Wait retry_after seconds.
500 internal_error Retry with a back-off. Check the idempotency note before creating the payment again.

Rate limits

  • 60 requests per minute per IP address. When you exceed it, the API answers 429:
{
  "success": false,
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please try again later.",
  "retry_after": 60
}
  • 10 invalid-key attempts per hour per IP address answer 429 too_many_attempts.

Handle 429 with a back-off: wait retry_after seconds, then retry. Do not poll faster than you need. A reasonable rhythm for a pending order is once a minute for about 20 minutes.

Handling errors well

  • Show customers a simple message. Never show technical details, keys or raw API errors.
  • Log the error code and your own reference to investigate later. Never log keys or secrets.
  • For 500 and network timeouts, read GET /payments/reference/{reference} before you create a payment again, so you never charge twice.