Ordexs API v1 Get an API key

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"
  }
}
  • code is the contract. It never changes for a given situation, so branch on it.
  • message is 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.
  • details carries machine-readable extras when there are any: the failing fields, the missing scope, the existing order.
  • request_id identifies the request in Ordexs's logs. It's also in the Request-Id header of every response, successful or not. Include it when you contact support.

Which errors to retry

HTTPRetry?
400, 401, 402, 403, 404, 405, 413, 422No. The same request fails the same way: fix it first.
409Depends on the code: idempotency_in_progress yes, after a second; the others no.
429Yes, after the number of seconds in Retry-After.
500, 503Yes, with backoff, and with the same Idempotency-Key (see Idempotency). Nothing was changed.

Every error code

CodeHTTPMeaningWhat to do
invalid_request400A query parameter or path is malformed.Read message; it names the parameter.
invalid_json400The body is not valid JSON.Send a JSON object with Content-Type: application/json.
unknown_field400The body has a field this endpoint does not accept.Remove it. details.unknown_fields lists it. Typos land here.
authentication_required401No API key was sent.Send Authorization: Bearer <key>.
invalid_api_key401The key is wrong, revoked or deleted.Check for a copy-paste error, or create a new key.
plan_required402The store is not on a plan that includes the API.The merchant upgrades. Keys are paused, not deleted, and come back.
insufficient_scope403The key lacks the scope this endpoint needs.details.required_scope names it. Edit the key in the dashboard.
forbidden403The key may not do this to this object.Read message; it names the rule.
store_suspended403The store is suspended by Ordexs.The merchant contacts Ordexs support.
store_paused403The store is paused, so it takes no new orders.The merchant resumes the store in the dashboard.
store_restricted403The store is restricted, usually for an unpaid invoice.The merchant settles billing in the dashboard.
not_found404No object with that id in this store.Check the id, and that the key belongs to the same store and mode.
method_not_allowed405That path does not accept this HTTP method.Check the method in the reference.
idempotency_in_progress409A request with the same Idempotency-Key is still running.Wait a second and retry with the same key.
invalid_state_transition409The object is in a state that does not allow this.Read the current status; for example a shipped order cannot be edited.
duplicate_external_id409An order with this external_id and source_name already exists.details.order_id is the existing order: use it instead of creating another.
duplicate_customer409A customer with this phone or email already exists.details.customer_id is the existing customer: update it instead.
duplicate_discount_code409Another 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_large413The body is over 256 KB.Send less per request.
validation_failed422One or more fields are invalid.details.fields lists each field and what is wrong with it.
request_rejected422The store refused the request for a business reason.message says why, in a sentence you can show a person.
out_of_stock422Not enough stock for a line item.Lower the quantity or pick another variant.
region_unknown422The region code is not one of the country’s regions.Use a code from GET /v1/regions.
country_not_served422The store does not deliver to that country.Use one of the store’s countries.
delivery_unavailable422The store has no delivery option for that address and mode.Check GET /v1/delivery/rates for what is offered.
idempotency_key_reused422The Idempotency-Key was already used with a different body.Use a new key for a different request.
quota_exceeded422A plan limit was reached (endpoints, keys, orders).message names the limit. The merchant upgrades or removes something.
courier_not_configured422No 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_rejected422The 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_limited429The store sent more requests per minute than its plan allows.Wait the number of seconds in Retry-After, then retry.
internal_error500Ordexs failed unexpectedly. Nothing was changed.Retry with the same Idempotency-Key. If it persists, send support the request_id.
upstream_unavailable503A 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".