Working with the API
Errors
Every error has the same shape, a stable code to branch on and a plain sentence that says what went wrong and what to do.
The error object
Any response that isn't a 2xx has this body:
{
"error": {
"code": "validation_failed",
"message": "customer.phone isn't a valid phone number for Algeria. (1 more problem listed in details.fields.)",
"details": {
"fields": [
{ "field": "customer.phone", "message": "customer.phone isn't a valid phone number for Algeria." },
{ "field": "line_items.0.quantity", "message": "line_items.0.quantity must be at least 1." }
]
},
"request_id": "req_7f3a9c2e41b84d0c9a1e5f6b"
}
}codeis the contract. It never changes for a given situation, so branch on it.messageis a full sentence written for a person: it names the field, the value or the rule, and says what to do. You can log it, or show it to the merchant. Don't parse it; its wording can improve.detailscarries machine-readable extras when there are any: the failing fields, the missing scope, the existing order.request_ididentifies the request in Ordexs's logs. It's also in theRequest-Idheader of every response, successful or not. Include it when you contact support.
Which errors to retry
| HTTP | Retry? |
|---|---|
400, 401, 402, 403, 404, 405, 413, 422 | No. The same request fails the same way: fix it first. |
409 | Depends on the code: idempotency_in_progress yes, after a second; the others no. |
429 | Yes, after the number of seconds in Retry-After. |
500, 503 | Yes, with backoff, and with the same Idempotency-Key (see Idempotency). Nothing was changed. |
Every error code
| Code | HTTP | Meaning | What to do |
|---|---|---|---|
invalid_request | 400 | A query parameter or path is malformed. | Read message; it names the parameter. |
invalid_json | 400 | The body is not valid JSON. | Send a JSON object with Content-Type: application/json. |
unknown_field | 400 | The body has a field this endpoint does not accept. | Remove it. details.unknown_fields lists it. Typos land here. |
authentication_required | 401 | No API key was sent. | Send Authorization: Bearer <key>. |
invalid_api_key | 401 | The key is wrong, revoked or deleted. | Check for a copy-paste error, or create a new key. |
plan_required | 402 | The store is not on a plan that includes the API. | The merchant upgrades. Keys are paused, not deleted, and come back. |
insufficient_scope | 403 | The key lacks the scope this endpoint needs. | details.required_scope names it. Edit the key in the dashboard. |
forbidden | 403 | The key may not do this to this object. | Read message; it names the rule. |
store_suspended | 403 | The store is suspended by Ordexs. | The merchant contacts Ordexs support. |
store_paused | 403 | The store is paused, so it takes no new orders. | The merchant resumes the store in the dashboard. |
store_restricted | 403 | The store is restricted, usually for an unpaid invoice. | The merchant settles billing in the dashboard. |
not_found | 404 | No object with that id in this store. | Check the id, and that the key belongs to the same store and mode. |
method_not_allowed | 405 | That path does not accept this HTTP method. | Check the method in the reference. |
idempotency_in_progress | 409 | A request with the same Idempotency-Key is still running. | Wait a second and retry with the same key. |
invalid_state_transition | 409 | The object is in a state that does not allow this. | Read the current status; for example a shipped order cannot be edited. |
duplicate_external_id | 409 | An order with this external_id and source_name already exists. | details.order_id is the existing order: use it instead of creating another. |
duplicate_customer | 409 | A customer with this phone or email already exists. | details.customer_id is the existing customer: update it instead. |
duplicate_discount_code | 409 | Another discount in this store already uses this code (codes ignore letter case). | Pick another code, or update the existing discount (find it with GET /v1/discounts?code=…). |
payload_too_large | 413 | The body is over 256 KB. | Send less per request. |
validation_failed | 422 | One or more fields are invalid. | details.fields lists each field and what is wrong with it. |
request_rejected | 422 | The store refused the request for a business reason. | message says why, in a sentence you can show a person. |
out_of_stock | 422 | Not enough stock for a line item. | Lower the quantity or pick another variant. |
region_unknown | 422 | The region code is not one of the country’s regions. | Use a code from GET /v1/regions. |
country_not_served | 422 | The store does not deliver to that country. | Use one of the store’s countries. |
delivery_unavailable | 422 | The store has no delivery option for that address and mode. | Check GET /v1/delivery/rates for what is offered. |
idempotency_key_reused | 422 | The Idempotency-Key was already used with a different body. | Use a new key for a different request. |
quota_exceeded | 422 | A plan limit was reached (endpoints, keys, orders). | message names the limit. The merchant upgrades or removes something. |
courier_not_configured | 422 | No courier account can take this parcel: the store has none connected, or none matches the order. | The merchant connects a courier, or sets a default or a routing rule. Or pass a courier_id from GET /v1/delivery/rates. |
courier_rejected | 422 | The courier refused the parcel. Its own reason is in message. | Fix what the courier names (often the address or the phone), then send again. details.shipment_id is the failed attempt. |
rate_limited | 429 | The store sent more requests per minute than its plan allows. | Wait the number of seconds in Retry-After, then retry. |
internal_error | 500 | Ordexs failed unexpectedly. Nothing was changed. | Retry with the same Idempotency-Key. If it persists, send support the request_id. |
upstream_unavailable | 503 | A service Ordexs depends on is briefly unreachable. Nothing was changed. | Retry after a few seconds. |
New codes may be added inside v1. Treat an unknown 4xx code as "don't retry" and an unknown 5xx as "retry later".
