GROperator

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, forbidden and validation_failed describe the kind of failure.
  • Business codes follow area.reason, for example shipment.not_found or merchant.possible_duplicate. The HTTP status follows the reason: 404 for "not found", 409 for conflicts and duplicates, 403 for "not allowed", and 422 for rule violations.
  • Place codes (geo_country_not_found, geo_city_not_found, geo_district_not_found, geo_city_ambiguous, geo_district_ambiguous) always answer 422 and carry level, input, field and candidates in details. See Places by name.
  • A request that breaks a business rule which has no code of its own answers 422 business_rule_violation with the explanation in message.

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

CodeHTTPWhat it allowsWhat to do
unauthorized401Authentication 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_credentials400The 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.
forbidden403The 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_disabled403The 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_required403The credential does not belong to a company (for example a platform user).Use an API key or a user of the shipping company.
tenant_blocked403The 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_failed400One 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_found404The route or resource does not exist.Check the path and the id.
idempotency_key_reused409This 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_limited429Too 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_violation422The 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_error500An 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

CodeHTTPWhat it allowsWhat to do
auth.invalid_credentials401The username or password is incorrect.Ask the user to check the credentials. Repeated failures lock the account.
auth.login_temporarily_blocked429Sign-in is temporarily blocked from this device or network after repeated failed attempts.Wait and try again later. Honour Retry-After.
auth.account_locked403The account is temporarily locked after repeated failed sign-in attempts.Wait for the lock to expire or ask a company admin.
auth.account_inactive403This account is not active.Ask a company admin to activate the user.
auth.invalid_refresh_token401The 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_suspended403The shipping company linked to this account is suspended.Contact the platform.
auth.company_expired403The contract of the shipping company linked to this account has expired.Contact the platform.
auth.company_access_denied403The company cannot be accessed in its current state.Contact the platform.

Places

CodeHTTPWhat it allowsWhat to do
geo_country_not_found422The 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_found422The 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_found422The district was not found in the given city.Let the user pick from candidates or from GET /geography/districts.
geo_city_ambiguous422The 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_ambiguous422The district name matches more than one district in the city.Use the district id from candidates.

Shipments, pricing and coverage

CodeHTTPWhat it allowsWhat to do
shipment.not_found404The shipment was not found. It is also returned for a shipment that belongs to someone else.Check the tracking number.
shipment.cannot_cancel422The 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_editable422A shipment in a final status (delivered, returned, cancelled…) cannot be edited.Check isEditable before offering an edit.
shipment.no_changes422No field was changed.Send at least one field with a new value.
shipment.field_locked_out_for_delivery422The shipment is out for delivery: only contact details, address and COD can be edited.Edit only those fields now.
shipment.invalid_status_transition422The shipment cannot move to that status from its current status.Re-read the shipment and act on its current status.
shipment.reverse_cod_not_allowed422Return shipments cannot carry a COD amount.Send codAmount 0 (or omit payment) for serviceType return.
shipment.service_type_locked422The service type cannot change once the linked return shipment exists.Cancel and create a new shipment instead.
shipment.multi_package_metrics422This shipment has several packages; weights and dimensions cannot be edited here.Cancel and create again if the parcel data was wrong.
shipment.access_denied403You are not allowed to access this shipment.Use a credential that owns the shipment.
shipment.concurrency_conflict409The shipment was changed by someone else at the same time.Read it again and retry the edit.
shipment.client_account_not_found404The merchant account is missing or invalid.Check sender.merchant.
shipment.client_account_inactive422The merchant account is not active.Activate the merchant in the dashboard.
shipment.branch_not_found404The branch was not found.Check pickup.branch against GET /branches.
branch.not_found404The branch was not found or is not active.Use an active branch id, code or name from GET /branches.
branch.ambiguous422More than one branch has this name.Use the branch code or id.
branch_coverage.no_coverage_for_city422No branch covers the pickup city.Choose the branch explicitly with pickup.branch.
branch_coverage.ambiguous_coverage422More than one branch covers the pickup city.Choose the branch explicitly with pickup.branch.
coverage.destination_not_covered422The 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_covered422The pickup city is outside the company’s coverage.Choose a pickup city that the company serves.
short_address.invalid422The short address must be 4 letters followed by 4 digits, for example RNBA6769.Validate the format in your form.
short_address.required_for_saudi_pickup422The 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_destination422The recipient’s short address is required for deliveries in Saudi Arabia.Send recipient.shortAddress.
district.required_for_destination422The recipient’s district is required.Send recipient.district.
district.required_for_pickup422The pickup district is required.Send pickup.district.
district.required_for_address422The district is required in the address.Send the district.
district.merchant_address_without_district422The merchant’s saved address has no district.Update the merchant address first, or send pickup explicitly.
quota.monthly_shipments_limit_reached403The company reached its monthly shipment limit.Contact the platform to raise the limit.
pricing.default_rate_card_not_found404The company has no rate card yet.Create a rate card in the dashboard.
pricing.city_not_found404The city was not found.Check the city.
pricing.merchant_not_found404The merchant account was not found.Check the merchant.

Merchants

CodeHTTPWhat it allowsWhat to do
merchant.not_found404The merchant was not found.Check the merchant id or name.
merchant.ambiguous422More than one merchant has this name. details.candidates lists them.Use the merchant id.
merchant.address_not_found404The address was not found for this merchant.List the merchant’s addresses and use one of their ids.
merchant.possible_duplicate409Data matching another merchant on the platform was found.If this really is a different store, send confirmPossibleDuplicate: true.
merchant.email_taken_format409The email belongs to an existing merchant on the platform.Use another contact email.
merchant.same_merchant_format409A merchant with the same name and commercial registration already exists on the platform.Use the existing merchant instead of creating a new one.

Webhooks

CodeHTTPWhat it allowsWhat to do
webhook.not_found404The webhook subscription was not found.List the merchant’s subscriptions and use one of their ids.
integrations.invalid_target_url422The webhook URL must be a public https address.Use an https URL reachable from the internet.
security.unsafe_webhook_target_url422The webhook URL points to a local or private address.Use a public address.
integrations.empty_events_list422Select at least one event.Send events, for example ["shipment.*"].