Errors
Error format and codes.
Every error is returned with a 4xx/5xx HTTP status and this body:
{
"success": false,
"error": {
"code": -1007,
"type": "validation",
"message": "Check the request fields",
"details": [{ "field": "quantity", "message": "Minimum 50" }]
},
"meta": { "requestId": "8e3c…", "timestamp": "2026-09-26T10:15:30.000Z", "processingTimeMs": 3 }
}codeis a stable numeric code, rely on it in your code;messagemay change and is translated according toAccept-Language.details: per-field errors (validation only).data: additional error data, if any.meta.requestIdmatches thex-request-idheader; include it when contacting support.
HTTP statuses
| Status | When | What to do |
|---|---|---|
400 | validation error (-1007), missing Idempotency-Key (-11001), invalid username (-9202), product (-9203) or externalId (-9204) | fix the request |
401 | missing, invalid or revoked key | check X-API-Key |
402 | insufficient balance (-9301) | top up the balance |
403 | IP is not in the Project allowlist | add the server address |
404 | order not found or belongs to another Project (-9201) | check the order id |
409 | a request with this Idempotency-Key is still in progress (-11003); externalId is already taken by an order with different parameters (-9207) | retry later or check the order |
422 | recipient not found (-9002), recipient cannot receive a gift (-9003), Idempotency-Key reused with a different body (-11002) | show the error to the buyer or use a new key; do not retry as is |
429 | rate limit exceeded (-11005) | retry after Retry-After |
502 | the supplier is temporarily unavailable (-9006) | retry in a few seconds |
5xx | an error on our side | retry with the same Idempotency-Key |
Code ranges
| Codes | Area |
|---|---|
-1000…-1999 | general (validation, access) |
-11001…-11099 | idempotency and limits |
-9001…-9099 | supplier (recipient not found, unavailable) |
-9201…-9299 | orders |
-9301…-9399 | prices and balance |
-9101…-9199 | Supplier Accounts |
-9401…-9499 | webhooks |
The full list of codes for each method is in the API reference.