Errors
A rejected request never creates an order and is never billed.
Shape
Every error, on every endpoint, is JSON with the same three fields, whether or not you send
Accept: application/json. Branch on failure_code; show
error_msg to a person.
{
"status": 0,
"error_msg": "The selected kind is invalid.",
"failure_code": "INVALID_REQUEST",
"errors": { "kind": ["The selected kind is invalid."] }
}
errors appears only on INVALID_REQUEST and lists every field that
failed. Every success is {"status": 1, "data": …, "meta": {"unix_timestamp": …}}.
Every failure_code
| HTTP | failure_code | Cause |
|---|---|---|
| 401 | UNAUTHENTICATED |
Signature, timestamp, nonce, key or IP allowlist. error_msg says which when it
can; a wrong key or merchant always reads "Authentication failed." |
| 404 | NOT_FOUND | No such order, product or endpoint. |
| 405 | METHOD_NOT_ALLOWED | Every endpoint is POST. |
| 422 | INVALID_REQUEST |
A field is missing or wrong. errors names each one. |
| 422 | INVALID_SKU, SKU_UNAVAILABLE,
NO_CONNECTION, INSUFFICIENT_BALANCE, CALLBACK_URL_REFUSED |
The order was refused. See Place an order. |
| 422 | NOT_REHITTABLE, ALREADY_RUNNING |
The rehit was refused. See Rehit an order. |
| 429 | RATE_LIMITED |
Too many requests, or 20 failed ones from your address in 5 minutes. Wait for
Retry-After, then send the same request again. |
| 500 | SERVER_ERROR |
Ours. On an order, check it by order_id before sending it again. |
Warning
Do not loop on a 401. Twenty locks your address out for five minutes, and the loop keeps it locked.
These are request errors. What happened to an order that was accepted is on Order status.