Skip to main content

Common API Errors and How to Fix Them

A practical guide to diagnosing and resolving the most common API errors when integrating with Anton Payments.

Written by Ryan O
Updated today

HTTP Error Reference

This guide covers every common error you will encounter when working with the Anton API, with practical steps to resolve each one.

400 Bad Request

The request body is malformed or missing required fields.

Common causes:

  • Invalid JSON syntax (trailing commas, unquoted keys).

  • Missing a required field such as amount, currency, or payee_id.

  • Incorrect data types (e.g., sending amount as a string instead of a number).

Example error response:

{
  "error": "bad_request",
  "message": "missing required field: currency"
}

Fix: Validate your JSON before sending. Check that all required fields listed in the API reference are present and correctly typed.

401 Unauthorized

Authentication failed.

Common causes:

  • Missing or malformed Authorization header. The correct format is Bearer ak_test_... or Bearer ak_live_....

  • Using a sandbox key (ak_test_) against production (api.antonpayments.com), or vice versa.

  • The API key has been revoked or rotated.

Fix: Verify you are using the correct key for the correct environment. Sandbox keys only work with api.antonpayments.dev. Production keys only work with api.antonpayments.com. If your key was recently rotated, retrieve the new key from the merchant portal.

403 Forbidden

You are authenticated but not authorized for this action.

Common causes:

  • A velocity rule blocked the operation — the response will include a code field identifying the rule.

  • Your account does not have permission for the requested endpoint or corridor.

Fix: Check the code field in the response body. If velocity-blocked, review the specific rule with your account manager. If a permissions issue, verify your account's enabled features in the merchant portal.

404 Not Found

The requested resource does not exist.

Common causes:

  • Incorrect ID — double-check the prefix (pay_, pye_, ins_) and the full ID string.

  • Wrong environment — sandbox and production are completely separate. A payout created in sandbox (api.antonpayments.dev) will not exist in production (api.antonpayments.com), and vice versa.

  • The resource was created under a different merchant account.

Fix: Verify the ID and the environment. Use GET /v1/payouts or GET /v1/payees to list your resources and confirm the correct IDs.

409 Conflict

A resource conflict occurred, typically related to idempotency.

Common causes:

  • You sent a request with an Idempotency-Key that was already used for a different request payload. Anton enforces that the same idempotency key must always be paired with the same request body.

Fix: Generate a new unique idempotency key (a UUID v4 is recommended) for each distinct request. If you are retrying a failed request, reuse the same key with the same payload.

422 Unprocessable Entity

The request is well-formed but contains invalid data.

Common causes:

  • Unsupported currency for the given corridor.

  • Invalid IBAN or account number format.

  • Payee is not in active status.

  • Amount is outside the allowed range for the corridor.

Example error response:

{
  "error": "validation_error",
  "details": [
    {"field": "currency", "message": "USD is not supported for this corridor"},
    {"field": "instrument_id", "message": "instrument is not active"}
  ]
}

Fix: Read the details array carefully. Each entry tells you which field failed and why. Use GET /v1/corridors and GET /v1/currencies to check supported values before creating payouts.

429 Too Many Requests

You have exceeded the API rate limit.

Fix: Check the Retry-After header in the response — it tells you how many seconds to wait before retrying. Implement exponential backoff in your integration. Typical rate limits are documented in your API agreement.

Retry-After: 30

502 / 503 Service Unavailable

A temporary issue with a downstream payment rail provider.

Fix: These errors are transient. Implement retry logic with exponential backoff (e.g., wait 1s, then 2s, then 4s, up to a maximum of 60s). Do not create duplicate payouts — use the same idempotency key when retrying. If errors persist for more than 15 minutes, contact support.

General Debugging Tips

  • Always log the full response body, not just the status code.

  • Use sandbox (api.antonpayments.dev) to test error handling before going live.

  • Include the request_id from the response headers when contacting support — it helps us trace your request immediately.

Did this answer your question?