OAuth Errors & Troubleshooting

Two response shapes you must handle#

Zid's standard error envelope#

{
  "status": "error",
  "message": {
    "type": "error",
    "code": "ERROR_SESSION_INVALID",
    "name": "Sorry",
    "description": "Invalid authentication"
  }
}

Validation errors use a different envelope#

{
  "status": "validation_error",
  "message": {
    "type": "validation_errors",
    "code": "ERROR_POPUP_OK",
    "name": "Inputs",
    "description": "Input errors!",
    "validations": [
      { "field": "email", "errors": ["The email field is required."] }
    ]
  }
}

1. Install & authorize errors#

https://web.zid.sa/…?error_code=EC3

⚠️ The merchant will not notice this. The dashboard does not currently render a
message for error_code, so from the merchant's point of view the install button simply
did nothing. When a merchant reports "installing your app does nothing", ask them to
paste the full URL from their address bar — the error_code is the only diagnostic
signal that exists.

The EC codes#

EC3 is the ambiguous one. "Merchant declined" and "app not visible to this store"
produce the identical code. Rule out the listing/private-grant cause first, because it is
the one you can fix.

Errors that are not redirects#

"Opening the authorize URL does nothing at all"#

Install checklist#

2. Token endpoint errors#

⚠️ Zid's token endpoint returns two different error shapes. Most failures come back in
Zid's standard envelope with HTTP 400. One specific failure comes back in the RFC 6749
shape. Handle both — branch on whether the body has a top-level error key.

Shape A — Zid envelope (most failures)#

{
  "status": "error",
  "message": {
    "type": "error",
    "code": null,
    "name": null,
    "description": "Client authentication failed"
  }
}

Note on status codes: these are returned as 400 even where RFC 6749 specifies a
different status — invalid_client, for example, is 400 here rather than 401. Do not
dispatch on the HTTP status alone at this endpoint; read the description.

invalid_grant — the five causes, in order of likelihood#

Shape B — RFC 6749 shape (one specific failure)#

{
  "error": "invalid_request",
  "error_description": "App installation is not allowed"
}

3. API request errors#

401 — authentication#

🚨 A missing scope returns 401, not 403.

This is the single most expensive trap in Zid's auth surface. The natural reaction to a
401 is "token expired → refresh" — but the refreshed token carries the same scopes, so
the next call 401s again, and your client loops until it trips the rate limiter and starts
returning 429 instead.

How to tell it apart from a real expiry: a scope 401 has message.code: null and a
description naming a scope, and it does not go away after a successful refresh.

Defensive rule: never retry a 401 more than once per token. Refresh at most once, and
if the same endpoint 401s again with the new token, stop and treat it as a scope problem.

Fix: add the scope to your app in the Partner Dashboard. Existing merchants must then
re-approve it — see Scope and consent errors.

403 — authorized, but not allowed#

The 403s split cleanly into two groups. APP_PERMISSIONS_PENDING_APPROVAL and
APP_PERMISSION_REMOVED are your problem (scope configuration). Everything else is
the merchant's account state and no amount of retrying or re-authorizing will change
it. Surface those to the merchant rather than to your error logs.

404, 422, 429, 500#

Scope and consent errors#

When you add a scope to a live app#

How the merchant re-approves#

Deactivating does not cancel your subscription. If the store has a paid subscription
to the app, deactivating leaves it untouched — the merchant can reactivate at any time
while the subscription is still valid, at no extra cost.

🚨 If your app uses a wildcard token, adding a scope takes the whole integration down
for that merchant. A wildcard token cannot express "everything except these two", so
Zid withholds the app entirely — every endpoint returns
403 APP_PERMISSIONS_PENDING_APPROVAL — until the merchant re-approves.

Plan wildcard-token scope changes like a release: notify merchants first, expect a
re-consent window, and do not ship on a Friday.

When a scope is removed from your app#

Handling consent states well#

To finish updating the app's permissions, please open your Zid dashboard, deactivate
the app and then activate it again. Your subscription is not affected — you can
reactivate at any time while it is valid, at no extra cost.

429 — rate limiting#

Your errors are in Arabic#

Uninstalls, revocation, and propagation delay#

An uninstalled app and an expired session return the identical error — 401 with
ERROR_SESSION_INVALID and "Login session expired." The distinguishing test is whether a
refresh fixes it. See the decision tree.

One webhook caveat: app.market.application.authorized is dispatched during the
authorize step, before the token exchange completes. An install can therefore fail
after you have already received authorized. Use app.market.application.install as
your signal that an installation is real and usable.

The decision tree#

A request failed. Where?
│
├─ The merchant clicked Install and landed on their dashboard
│  └─ Read ?error_code= from the URL they paste → §1 EC table
│     ├─ no error_code at all → merchant was not logged in
│     └─ a Zid-branded error card instead → read the card; it's accurate
│
├─ POST /oauth/token returned an error
│  ├─ body has a top-level "error" key
│  │  └─ "App installation is not allowed" → no active app subscription; merchant must
│  │     subscribe, then reinstall
│  └─ body is Zid's envelope (code: null) → read message.description
│     ├─ "Client authentication failed"  → client_id / client_secret / wrong environment
│     ├─ "...grant...is invalid, expired..." → work the 5 invalid_grant causes in order
│     └─ "The refresh token is invalid"  → refresh token dead (1y expiry, reused, or
│                                           uninstalled) → restart install flow
│
└─ An API call to api.zid.sa failed
   │
   ├─ 429 → honour Retry-After, back off per store.
   │        Low real traffic? Look for a 401 loop underneath.
   │
   ├─ 403 → is message.code APP_PERMISSIONS_PENDING_APPROVAL / APP_PERMISSION_REMOVED?
   │        ├─ yes → YOUR scope config. Do NOT retry on a timer.
   │        │        PENDING_APPROVAL → merchant deactivates + reactivates the app
   │        │           (subscription unaffected). Be ready to store the NEW tokens.
   │        │        PERMISSION_REMOVED → restore the scope in the Partner Dashboard.
   │        └─ no  → MERCHANT account state (subscription, verification, readiness,
   │                 permissions, demo store). Not fixable by you — surface it to them.
   │
   ├─ 422 → validation envelope; read message.validations[]
   │
   ├─ 404 ERROR_SESSION_INVALID → store missing; open a ticket with the store id
   │
   └─ 401 → Refresh the token ONCE.
            │
            ├─ Refresh succeeded, call now works
            │     → ordinary expiry. You are refreshing too late:
            │       move to a scheduled refresh (~every 10 months).
            │
            ├─ Refresh succeeded, call still 401s
            │     → MISSING SCOPE. Stop retrying immediately.
            │       Add the scope; existing merchants must re-approve.
            │
            └─ Refresh itself failed
                  → the merchant uninstalled (or tokens were revoked).
                    Mark the installation inactive. Wait for a reinstall.

Preventive checklist#

Getting help#

Related#