Error reference
Every response that is not 2xx has the same body, described in Conventions: code, message, status, details and traceId. Program against the code, which is stable. The message is Arabic by default and English when Accept-Language prefers English, and may be improved over time.
- Generic codes such as
unauthorized,forbiddenandvalidation_faileddescribe the kind of failure. - Business codes follow
area.reason, for exampleshipment.not_foundormerchant.possible_duplicate. The HTTP status follows the reason:404for "not found",409for conflicts and duplicates,403for "not allowed", and422for rule violations. - Place codes (
geo_country_not_found,geo_city_not_found,geo_district_not_found,geo_city_ambiguous,geo_district_ambiguous) always answer422and carrylevel,input,fieldandcandidatesindetails. See Places by name. - A request that breaks a business rule which has no code of its own answers
422 business_rule_violationwith the explanation inmessage.
This catalogue is written by hand from the public API's error definitions. The server builds its full code list automatically from its internal error texts, so it cannot be extracted when this site is built; the table lists the codes the public endpoints document and that integrators meet in practice. The status is the usual one for the code. Some conditions can also be reported as validation_failed with the failing field path in details.errors: a missing Saudi short address on a shipment is an example. Always handle the generic statuses (400, 401, 403, 404, 409, 422, 429, 500) as a fallback for a code you do not recognise.
General codes
| Code | HTTP | What it allows | What to do |
|---|---|---|---|
unauthorized | 401 | Authentication is missing or the credentials are wrong. The message says which: the secret header is missing, the key or secret is incorrect, or the key is revoked or expired. | Send both X-API-Key and X-API-Secret, or a valid bearer token. Create a new key if the old one was revoked or expired. Renew an expired access token with /auth/refresh. |
ambiguous_credentials | 400 | The request carries both an Authorization: Bearer token and an X-API-Key header. | Send exactly one kind of credential. Check for a proxy or client that adds an extra header. |
forbidden | 403 | The credential is valid but lacks the permission. details.requiredScope names the scope the operation needs. A password login also needs the exact dashboard permission (orders:create, orders:update, orders:cancel for shipment writes). | Add the scope to the key in the dashboard (Settings, API access) or use a user with the matching permission. A merchant login also gets this when it asks for another merchant’s data. |
channel_disabled | 403 | The public API is not enabled for this company: the platform has not granted the channel, or the company admin has not switched it on. | Ask the platform to grant the API integration channel, then switch it on in Settings, Company. Nothing to fix in your code. |
company_required | 403 | The credential does not belong to a company (for example a platform user). | Use an API key or a user of the shipping company. |
tenant_blocked | 403 | The company account is suspended or its contract has expired. Checked on every request, so existing keys and tokens stop working at once. | Contact the platform. Requests succeed again when the company is reactivated. |
validation_failed | 400 | One or more fields are invalid, including numbers above their upper bound (for example Weight is too large). details.errors maps each field path (for example recipient.phone) to its messages. | Fix every listed field and send the request again. Show the messages next to your form fields. |
not_found | 404 | The route or resource does not exist. | Check the path and the id. |
idempotency_key_reused | 409 | This Idempotency-Key was already used with a different request body. | Use a new key for a new request. Reuse a key only to retry the exact same body. |
rate_limited | 429 | Too many requests, from this IP address (before authentication) or from this key or user (after it). The Retry-After header gives the seconds to wait. | Wait for Retry-After, then retry. Spread bulk work over time and cache lookups (geography, statuses). |
business_rule_violation | 422 | The request is well formed but breaks a business rule that has no code of its own. The message explains it. | Read the message and change the data. Do not retry unchanged. |
internal_error | 500 | An unexpected server error. Quote traceId when you contact support. | Retry later with the same Idempotency-Key. If it persists, contact support with the traceId. |
Sign-in codes
| Code | HTTP | What it allows | What to do |
|---|---|---|---|
auth.invalid_credentials | 401 | The username or password is incorrect. | Ask the user to check the credentials. Repeated failures lock the account. |
auth.login_temporarily_blocked | 429 | Sign-in is temporarily blocked from this device or network after repeated failed attempts. | Wait and try again later. Honour Retry-After. |
auth.account_locked | 403 | The account is temporarily locked after repeated failed sign-in attempts. | Wait for the lock to expire or ask a company admin. |
auth.account_inactive | 403 | This account is not active. | Ask a company admin to activate the user. |
auth.invalid_refresh_token | 401 | The refresh token is invalid or expired. Refresh tokens are single use. | Sign in again with username and password. Always store the new refresh token returned by /auth/refresh. |
auth.company_suspended | 403 | The shipping company linked to this account is suspended. | Contact the platform. |
auth.company_expired | 403 | The contract of the shipping company linked to this account has expired. | Contact the platform. |
auth.company_access_denied | 403 | The company cannot be accessed in its current state. | Contact the platform. |
Places
| Code | HTTP | What it allows | What to do |
|---|---|---|---|
geo_country_not_found | 422 | The country was not found or is not active. details has level, input, field and candidates. | Use an ISO code (SA), an id or an existing name. Show candidates to the user. |
geo_city_not_found | 422 | The city was not found in the given country. | Let the user pick from candidates or from GET /geography/cities. Nothing is created from an API call. |
geo_district_not_found | 422 | The district was not found in the given city. | Let the user pick from candidates or from GET /geography/districts. |
geo_city_ambiguous | 422 | The city name matches more than one city (for example in two countries). | Send country as well, or use the city id from candidates. |
geo_district_ambiguous | 422 | The district name matches more than one district in the city. | Use the district id from candidates. |
Shipments, pricing and coverage
| Code | HTTP | What it allows | What to do |
|---|---|---|---|
shipment.not_found | 404 | The shipment was not found. It is also returned for a shipment that belongs to someone else. | Check the tracking number. |
shipment.cannot_cancel | 422 | The shipment can no longer be cancelled in its current status. Cancelling is possible while it is a draft, created or scheduled for pickup. | Read the current status first (canCancel on the shipment). Later stages go through the return flow. |
shipment.not_editable | 422 | A shipment in a final status (delivered, returned, cancelled…) cannot be edited. | Check isEditable before offering an edit. |
shipment.no_changes | 422 | No field was changed. | Send at least one field with a new value. |
shipment.field_locked_out_for_delivery | 422 | The shipment is out for delivery: only contact details, address and COD can be edited. | Edit only those fields now. |
shipment.invalid_status_transition | 422 | The shipment cannot move to that status from its current status. | Re-read the shipment and act on its current status. |
shipment.reverse_cod_not_allowed | 422 | Return shipments cannot carry a COD amount. | Send codAmount 0 (or omit payment) for serviceType return. |
shipment.service_type_locked | 422 | The service type cannot change once the linked return shipment exists. | Cancel and create a new shipment instead. |
shipment.multi_package_metrics | 422 | This shipment has several packages; weights and dimensions cannot be edited here. | Cancel and create again if the parcel data was wrong. |
shipment.access_denied | 403 | You are not allowed to access this shipment. | Use a credential that owns the shipment. |
shipment.concurrency_conflict | 409 | The shipment was changed by someone else at the same time. | Read it again and retry the edit. |
shipment.client_account_not_found | 404 | The merchant account is missing or invalid. | Check sender.merchant. |
shipment.client_account_inactive | 422 | The merchant account is not active. | Activate the merchant in the dashboard. |
shipment.branch_not_found | 404 | The branch was not found. | Check pickup.branch against GET /branches. |
branch.not_found | 404 | The branch was not found or is not active. | Use an active branch id, code or name from GET /branches. |
branch.ambiguous | 422 | More than one branch has this name. | Use the branch code or id. |
branch_coverage.no_coverage_for_city | 422 | No branch covers the pickup city. | Choose the branch explicitly with pickup.branch. |
branch_coverage.ambiguous_coverage | 422 | More than one branch covers the pickup city. | Choose the branch explicitly with pickup.branch. |
coverage.destination_not_covered | 422 | The recipient’s city is outside the company’s coverage. | Check GET /geography/coverage before the order. A price quote reports this as deliverable: false instead of an error. |
coverage.pickup_not_covered | 422 | The pickup city is outside the company’s coverage. | Choose a pickup city that the company serves. |
short_address.invalid | 422 | The short address must be 4 letters followed by 4 digits, for example RNBA6769. | Validate the format in your form. |
short_address.required_for_saudi_pickup | 422 | The sender’s short address is required for pickups in Saudi Arabia. | Send pickup.shortAddress. Note: the same rule is usually reported as validation_failed with the field path. |
short_address.required_for_saudi_destination | 422 | The recipient’s short address is required for deliveries in Saudi Arabia. | Send recipient.shortAddress. |
district.required_for_destination | 422 | The recipient’s district is required. | Send recipient.district. |
district.required_for_pickup | 422 | The pickup district is required. | Send pickup.district. |
district.required_for_address | 422 | The district is required in the address. | Send the district. |
district.merchant_address_without_district | 422 | The merchant’s saved address has no district. | Update the merchant address first, or send pickup explicitly. |
quota.monthly_shipments_limit_reached | 403 | The company reached its monthly shipment limit. | Contact the platform to raise the limit. |
pricing.default_rate_card_not_found | 404 | The company has no rate card yet. | Create a rate card in the dashboard. |
pricing.city_not_found | 404 | The city was not found. | Check the city. |
pricing.merchant_not_found | 404 | The merchant account was not found. | Check the merchant. |
Merchants
| Code | HTTP | What it allows | What to do |
|---|---|---|---|
merchant.not_found | 404 | The merchant was not found. | Check the merchant id or name. |
merchant.ambiguous | 422 | More than one merchant has this name. details.candidates lists them. | Use the merchant id. |
merchant.address_not_found | 404 | The address was not found for this merchant. | List the merchant’s addresses and use one of their ids. |
merchant.possible_duplicate | 409 | Data matching another merchant on the platform was found. | If this really is a different store, send confirmPossibleDuplicate: true. |
merchant.email_taken_format | 409 | The email belongs to an existing merchant on the platform. | Use another contact email. |
merchant.same_merchant_format | 409 | A merchant with the same name and commercial registration already exists on the platform. | Use the existing merchant instead of creating a new one. |
Webhooks
| Code | HTTP | What it allows | What to do |
|---|---|---|---|
webhook.not_found | 404 | The webhook subscription was not found. | List the merchant’s subscriptions and use one of their ids. |
integrations.invalid_target_url | 422 | The webhook URL must be a public https address. | Use an https URL reachable from the internet. |
security.unsafe_webhook_target_url | 422 | The webhook URL points to a local or private address. | Use a public address. |
integrations.empty_events_list | 422 | Select at least one event. | Send events, for example ["shipment.*"]. |