Getting started

Errors

Errors use the HTTP status, and a JSON body with a stable code to branch on and a readable message.

422 Unprocessable Content

{
    "error": {
        "code": "validation_failed",
        "message": "Some fields are invalid.",
        "fields": {
            "amount_dzd": [
                "The amount dzd field must be at least 500."
            ]
        }
    }
}

Codes

Status	Code	Meaning
`401`	`unauthenticated`	No key, an unknown key, or a paused one.
`402`	`insufficient_credits`	Not enough credits to create the payment. `missing_credits` says how many.
`403`	`account_not_verified`	The account is not verified by an official document, or has no RIP.
`403`	`account_suspended`	The account is suspended.
`404`	`not_found`	No such resource in your account. Another account's payment answers 404 too.
`405`	`method_not_allowed`	This method is not allowed on this endpoint.
`409`	`invalid_state`	The payment is not in a status that allows this action (confirming a payment without a transaction number, cancelling one that ended). `message` says why.
`422`	`validation_failed`	A field is invalid. `fields` lists each field and its messages.
`422`	`limit_reached`	You already have the most webhook endpoints allowed.
`429`	`rate_limited`	Too many requests. Wait for `Retry-After` seconds.
`500`	`server_error`	Something went wrong on our side. Retry later.

Handling them

Branch on error.code, not on the message: messages may be reworded.
Retry 429 and 5xx later; never retry a 4xx unchanged.
Creating a payment is not idempotent: if a request times out, list your latest payments (created_after) before creating it again.