> ## Documentation Index > Fetch the complete documentation index at: https://docs.afriex.com/llms.txt > Use this file to discover all available pages before exploring further. # Errors > The error format, what each HTTP status means, and which errors to retry. Every error response has the same shape, so you can handle errors in one place. ## Error format ```json theme={null} { "code": "INVALID_BUSINESS_CUSTOMER_REQUEST", "error": "Invalid business customer request", "details": { "errorMessage": "Invalid business customer request", "friendlyMessage": "Invalid customer phone provided: PHONE_COUNTRY_MISMATCH" } } ``` | Field | Description | | - | - | | `code` | Machine-readable error code. Use it for logic in your integration. | | `error` | A fixed message for the `code`, such as `Invalid business customer request`. | | `details.errorMessage` | The same message as `error`. | | `details.friendlyMessage` | The specific problem with this request, such as which field is wrong. It can be empty, and it can include internal codes such as `PHONE_COUNTRY_MISMATCH`. | | `details.data` | Present on some errors only. For example, a `409` for an existing customer carries that customer's `customerId`. | Branch on `code` and the HTTP status. Log `details.friendlyMessage` to debug a request, but don't parse it, because the wording can change. To show an error to your own users, map `code` to your own text. See [Common error codes](/api-reference/models#common-error-codes) for the codes and their statuses. ## HTTP status codes | Status | Meaning | What to do | | - | - | - | | `200` | The request succeeded. Deleting a resource also returns `200`. | Nothing. | | `201` | The resource was created. | Nothing. | | `202` | The request was accepted. The [sandbox helpers](/guides/testing-in-sandbox) return this. | Nothing. | | `400` | The request is invalid, for example a business rule failed. | Fix the request. Don't retry it unchanged. | | `401` | The API key is missing, invalid, revoked, or doesn't have the [permission](/api-reference/permissions) the endpoint needs. | Check the key and its permissions. Don't retry. | | `402` | The wallet balance is too low to cover the request. | Fund the wallet, then send the request again. Don't retry before you have. | | `403` | The request is understood but refused: a business limit is exceeded, a customer or business isn't verified, or the endpoint isn't available to you. Sandbox-only endpoints return this in production. | Don't retry until the cause is fixed. | | `404` | The resource doesn't exist for your business. The `code` names the resource. | Check the ID. | | `409` | The request conflicts with something that exists, such as a duplicate transaction or a customer with the same email. | Don't send it again. Look up the existing resource. See [Idempotency](/api-reference/idempotency). | | `422` | The request failed schema validation, or it is valid but can't be done, for example an unsupported country, currency, channel, or virtual account type. `details.friendlyMessage` says which. | Fix the request and send it again. | | `429` | You sent too many requests. | Wait `Retry-After` seconds, then retry. See [Rate limits](/api-reference/rate-limits). | | `500` | An unexpected error on our side. | Retry with backoff. If it keeps happening, contact support. | | `503` | An upstream processor failed or timed out, or the API is briefly offline. | Retry with backoff, and honour `Retry-After` when it's present. | ## Business limits Afriex sets limits on your business. A transaction that would take you over a limit returns `403` with `BUSINESS_LIMIT_EXCEEDED`, and `details.friendlyMessage` names the limit and the period. A transaction below the smallest amount a limit allows returns `400` with `BUSINESS_TRANSACTION_MIN_AMOUNT_NOT_MET`. Usage for daily, weekly, and monthly limits resets on a fixed schedule, in UTC: | Limit period | Usage resets | | - | - | | Daily | Every day at 00:00 UTC | | Weekly | Every Monday at 00:00 UTC | | Monthly | On the 1st of each month at 00:00 UTC | After usage resets, a transaction that went over a daily, weekly, or monthly limit can go through. To ask about your limits, contact [support@afriex.com](mailto:support@afriex.com). ## Retrying Retry only the errors that can succeed on a second attempt: * **Retry:** `429`, `500`, `503`, and requests that time out or lose their connection. Treat a `502` or `504` the same way. * **Don't retry:** the other `4xx` errors. They fail the same way until you change the request. When you retry: 1. Wait before each attempt, and wait longer each time. For example, start at one second and double the wait, with a little random jitter so many clients don't retry together. 2. Use `Retry-After` when the response has it, instead of your own wait. 3. Stop after a few attempts, and surface the error. 4. For `POST /transaction`, retry with the same `meta.idempotencyKey`. A retry can never create a second transaction, and a `409` tells you the first attempt went through. See [Idempotency](/api-reference/idempotency). ## Request IDs Every API response, successful or not, carries an `x-request-id` header. It identifies that one request in Afriex's logs, including a `503` Afriex returns when the API is briefly unavailable. Log it next to each request you send, so you can find it again when something goes wrong. ```bash theme={null} curl -i -H "x-api-key: YOUR_API_KEY" \ https://sandbox.api.afriex.com/api/v1/customer # x-request-id: 5f3b1c0e2a7d94c5b8e6a1d2c3b4f5a6 ``` Treat it as an opaque string. Each request gets a new one. ## Getting help If a `500` or `503` persists, or a response doesn't make sense, contact [support@afriex.com](mailto:support@afriex.com) with the `x-request-id` of the request. Add the endpoint, the time, and the `code` you received. For a webhook question, send the event's `id` from the webhook body instead. See [Webhooks](/api-reference/endpoint/webhooks/introduction#duplicates-ordering-and-replays). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.