HTTP 429 and rate limit errors

What it means#

HTTP 429 ("too many requests") means a limit was reached and the request was not carried out: nothing is created or charged. The platform has several independent limits, and the shape of the answer shows which one you hit.

Who is affected#

Developers calling /api/v1 (merchant key) or /api/company/v1 (company key), visitors of public pages such as the parcel tracking link page, people signing in or registering, and users of the mobile apps.

Likely causes#

Good to know:

• IP counters are shared. All routes with a plain per-minute limit add to one counter per IP address, whichever domain or host the request used, so all keys and applications behind the same public IP address share it. Routes that have their own limit inside an already limited group count twice: POST /parcels, GET /statement, POST /webhooks, the webhook test (POST /webhooks/{id}/test) and the company POST /parcels. The usable rate on those routes is therefore roughly half of the configured route limit (for example about 30 parcel creations per minute with the merchant API), and never more than the 60 per minute that apply to all of /api.
• Fixed windows. A minute window starts at the first counted request. The daily plan counter resets at 00:00 UTC.
• Plan values. A new plan form is pre-filled with 60 per minute and 5,000 per day (merchants) or 120 and 20,000 (companies). Empty or 0 means no limit.
• Message text. Plan-limit messages are localized, and the English text can read awkwardly, for example "You have reached your plan limit: 60 order Per minute. Wait 42 seconds or upgrade your plan."

How to diagnose#

Repeat a call with -i and Accept: application/json, then read the body and headers:

curl -i https://YOUR_DOMAIN/api/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

• rate_limited is your plan. Merchants open Plan and subscription and read API requests today under Your plan usage. Company admins read the usage on Integrations and API, or call GET /api/company/v1/me.
• Too Many Attempts. is an IP limit. Compare X-RateLimit-Limit with the number of calls per minute made from your whole public IP address, including other applications.
• An HTML page means the request had no JSON Accept header, or it was a page. Note the H… reference and the time.

Resolution steps#

1. Wait for the window

   Pause for the Retry-After seconds (or retry_after) and then retry. A daily plan limit can mean a wait of hours.

2. Slow down and spread the calls

   Add a delay with a random jitter between calls and avoid many workers from one IP address. Cache lists that rarely change, such as /governorates and /companies, and use webhooks instead of polling.

3. Retry creation safely

   Send a reference with POST /parcels so a repeated request is recognised. On the merchant API a retry returns the existing parcel (HTTP 200, "duplicate": true) instead of creating another one. On the company API the same reference for the same merchant returns 409 duplicate_reference: treat it as already created and fetch the parcel with GET /parcels/{reference} (that lookup covers all merchants of your company, so if they can share a reference, use GET /parcels?reference=…&merchant_id=…). The idempotency article has the details.

4. Raise the plan limit

   If you hit the plan limit regularly, ask the platform to move you to a plan with higher limits. Plan limits are set per plan by the super admin; the IP limits are fixed and cannot be raised per account.

When to contact support#

• You get 429 at low volume although only your own system uses the IP address.
• The usage counter in the panel does not match your calls.
• Quote the H… reference, the URL and the time when you report an HTML 429 page.