Error codes — Documentation Aventopay

Standard format

All API errors return JSON {error, message}. The HTTP code indicates the category, the message field details the cause.

Response structure

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Bad Request",
  "message": "amount must be a positive integer in cents"
}

Code	Cause	Fix
`400` Bad Request	Missing parameter, invalid JSON, zero or negative amount.	Check request structure and JSON format.
`401` Unauthorized	Missing/invalid API Key, incorrect HMAC signature, unknown merchant_id.	Check Authorization and X-Aventopay-Signature headers (signature on raw body, identical string).
`403` Forbidden	Blocked request (velocity limits, suspended activity).	Check the dashboard for the reason; contact support if needed.
`404` Not Found	Non-existent endpoint or resource (wrong URL, unknown session).	Check the path and the provided identifier.
`405` Method Not Allowed	Unsupported HTTP verb.	Use POST on /api/payment/session.
`409` Conflict	transaction_id already used for this merchant.	Use a unique identifier per transaction.
`413` Payload Too Large	Request body exceeds accepted limit.	Reduce metadata and free fields size.
`422` Unprocessable Entity	Valid format but inconsistent data (e.g. unsupported currency).	Check values against the API reference.
`429` Too Many Requests	Rate limit exceeded or anti-fraud velocity.	Wait retry_after_minutes and retry with exponential backoff.
`500` Internal Server Error	Unexpected error on Aventopay side.	Retry with backoff. Contact support if persistent.

Never replay a 400/401/409 as-is — fix the request first.
For 429 and 500, apply exponential backoff: 1s, 2s, 4s, up to 30s max.
Log the response body for diagnosis — the message field indicates the field involved.
Distinguish client errors (4xx) from server errors (5xx) in your monitoring.

See also Webhooks for the response codes expected on your server.