Errors and status codes

Purpose#

This page lists the HTTP status codes and error codes that the merchant API (/api/v1) and the company API (/api/company/v1) really return, what each one means and how to fix it. Build your error handling on error.code.

The error shape#

Success is 200, or 201 when a new resource is created, such as a parcel or a webhook endpoint. A 200 with "duplicate": true means that the reference already exists (merchant API). Every error raised by the API itself looks like this:

{
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "...",
    "fields": { "customer_phone": ["..."] }
  }
}

• code is a short snake_case code: the value to program against.
• message is text in the request language: Arabic by default, English with Accept-Language: en. A few messages exist only in Arabic, so never branch on the text.
• fields appears on most validation errors: field names with their messages, and message normally repeats the first of those messages (the exception is the company API merchant_id error: fields.merchant_id says "Merchant not found in your company." while message has the longer merchant_id text shown in the validation table). A few company API errors (an unknown stage, a missing or foreign deliveryman_id, an unknown action) carry only message. The field names are the platform's internal ones (customer_name, customer_phone, customer_address, customer_city, lat, long, and shop_id instead of pickup_location_id).
• retry_after (seconds) appears on rate_limited, reference on server_error and response_status on delivery_failed.

The order of the checks#

Each call goes through these checks and stops at the first failure. After them, the endpoint applies its own validation and business rules.

Status codes and error codes#

Two of these extra keys, retry_after and reference, look like this:

{
  "success": false,
  "error": {
    "code": "rate_limited",
    "message": "...",
    "retry_after": 42
  }
}

{
  "success": false,
  "error": {
    "code": "server_error",
    "message": "...",
    "reference": "E3FA91C"
  }
}

Validation errors (422)#

fields maps each failing field to its messages. These are the fields you meet most:

Errors outside this shape#

A few errors are produced before the API code runs, so they do not use the envelope:

• An unknown path (404), a wrong HTTP method (405) and the general and route request limits (429). With Accept: application/json you get a JSON body with a message; without it you get an HTML page.
• With the JSON header these limits answer with {"message": "Too Many Attempts."} and the headers Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A 429 can therefore come from three places: the general limit of 60 requests per minute per IP address and the per-route limits (no error.code), and the plan limit (rate_limited in the envelope).
• Rarely, an unexpected failure that happens before the API's own error handling returns {"success": false, "message": "..."} with 500.

{ "message": "Too Many Attempts." }

Handling errors in your client#

1. Check the HTTP status first

   A 4xx means your request must change, except 429. A 5xx is normally a problem on the platform side: retry later. One case does not go away by retrying: in the company API, assigning a courier to a parcel whose status cannot move to Delivery Man Assign (for example a Pending one or one still in pickup) returns 500 and server_error every time, so check the parcel's status_code before calling assign.

2. Branch on error.code

   Use error.code for logic, error.fields to highlight inputs and error.message only to display to a person.

3. Wait on 429

   Pause for error.retry_after seconds, or for the Retry-After header when the general or a route limit answered (no error.code), then retry.

4. Make creation retries safe

   After a timeout or a 500 on parcel creation, look the parcel up before creating it again: with GET /parcels/{reference} in the merchant API, and with GET /parcels?merchant_id=<id>&reference=<reference> in the company API (a bare GET /parcels/{reference} there searches all your merchants and can return another merchant's parcel). In the merchant API, sending the same reference again returns the existing parcel with "duplicate": true.

Common mistakes#

• Treating 200 with "duplicate": true as a new parcel. It is the parcel you created before.
• Expecting 409 for a repeated reference in the merchant API. That is the company API; the merchant API returns the old parcel.
• Retrying a 4xx unchanged. Fix the request first.
• Parsing error.message. It changes with the language; some messages are Arabic only.
• Not sending Accept: application/json. Errors raised before the API code runs (see "Errors outside this shape") then arrive as HTML pages.
• Ignoring fields. When present, it names the exact input that failed.

Limits and permissions#

• plan_feature, rate_limited and api_not_allowed depend on your plan and account type, not on the request body.
• Only the languages ar and en are used for messages.
• The codes marked merchant or company exist only on that API.