Troubleshooting apps

Errors come back in the usual envelope. Read error.message:

{ "success": false, "error": { "code": "HTTP_ERROR", "message": "Invalid or revoked app token" } }

API calls

You get	It means	Do
`401` `Invalid or revoked app token`	The app was uninstalled or disabled on that store, NUMU suspended it or paused all partner apps, the token was replaced more than 24 hours ago, or you revoked it	Treat it as an uninstall of that store: stop its jobs and delete the token
`403` `Access token lacks the '…' scope`	The merchant did not grant that scope	Add the scope to your manifest in a new version, then ask the merchant to approve it
`403` `Access token does not permit this operation`	The route needs a scope apps never get, such as anything under `settings`	Apps cannot reach it. See Scopes
`403` `Access token is bound to a different store`	The `store_id` in the path is not the token's store	Use the token saved for that store
`403` with an HTML body and `server: cloudflare`	The CDN refused the request before it reached the API	Send a normal `User-Agent` and retry. If it persists, send us the `cf-ray` value
`404` on a route that exists	A missing or extra trailing slash	Collections end in `/` (`/orders/`), single items don't (`/orders/{id}`)
`409` on a write	A request with the same `Idempotency-Key` is still running	Wait, then retry with the same key
`429`	Over 300 requests a minute on this token	Wait `Retry-After` seconds, then back off with jitter

These appear on the consent screen, or in the error from /oauth/token:

Message	Do
`redirect_uri does not match the app's registered redirect URLs`	Send exactly one of your `redirect_urls`, byte for byte: the scheme, the host, the path and any trailing slash
`missing required scopes: …`	`scope` must include every scope in `oauth.scopes`
`scope not declared by the app: …`	Ask only for scopes in `oauth.scopes` or `oauth.optional_scopes`
`state is required`	Send a `state`
`This app is not published yet.`	Before publishing, the app installs only on your own development stores
`This app is not available right now.`	NUMU suspended the app, or paused all partner apps
`This store's plan allows N Partner Apps.`	The store reached its plan's limit of partner apps
`invalid client credentials`	Wrong `client_id` or `client_secret`. After a rotation, only the new secret works
`invalid, expired or already used code`	A code works once and for 10 minutes. Start the install again

A signature that never matches usually means one of these:

The body was parsed or re-serialised before hashing. Hash the raw bytes.

The webhook t= prefix was left out: the signed string is <timestamp>.<raw body>.

The two schemes were mixed up. Webhooks sign <timestamp>.<body>; the install redirect and Open app sign the sorted name=value query string.

app_url has a query string of its own, or state holds characters beyond letters, digits, - and _.

An old client secret is still deployed.

Message	Do
The Partner program isn't open yet	The program opens by invitation. Write to engineering@numueg.app
`Verify your email before applying.`	Open the email NUMU sent when you signed up and verify your address
`You already have a partner account (pending).`	Your application is waiting for review. It cannot be edited meanwhile
`Accept the current Partner Agreement first.`	In the portal, choose Accept version …
`That subdomain is taken.`	Choose another subdomain for the development store
`That slug is taken.`	Choose another slug. A slug belongs to one app forever
`Write the Arabic name in Arabic, not the English.`	Write the Arabic name in Arabic
`That isn't valid JSON.`	`numu.app.json` has a syntax error: check commas and quotes
`v… is already in review; wait for NUMU's decision first`	One version per app can be in review. Wait for the decision

Message	Do
`…: not found. Are you an approved NUMU partner, and is the Partner program open?`	Your partner account is not approved yet, or the program is closed
`Login failed: this account has 2FA enabled.`	The CLI cannot sign in to accounts with two-factor authentication yet. Use the partner portal. A personal access token does not work for the partner commands either
`pricing.model: recurring is not available yet …`	NUMU billing for partner apps is not open. Use `free` or `external`
`version must be higher than …`	Raise `version` in `numu.app.json`

Arabic shows as ? or broken characters: your stack is not UTF-8 from end to end. On MySQL, use utf8mb4.