Errors

Every error response has the same shape, so you can handle errors in one place.

Error format

{
  "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 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 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 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.
`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.
`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.

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:

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.
Use Retry-After when the response has it, instead of your own wait.
Stop after a few attempts, and surface the error.
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.

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.

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 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.

Overview

Requests and responses

Balance

Checkout Sessions

Rates

Customers

Payment Methods

Media

Transactions

Payment Batches

SME Registration

Sandbox helpers

Webhooks

Error format

HTTP status codes

Business limits

Retrying

Request IDs

Getting help

​Error format

​HTTP status codes

​Business limits

​Retrying

​Request IDs

​Getting help

Error format

HTTP status codes

Business limits

Retrying

Request IDs

Getting help