Error shape
All error responses are JSON withContent-Type: application/json, but the body envelope differs by surface — a robust client branches on which key is present:
OAuth endpoints follow RFC 6749 §5.2 error codes in a
{ "error", "error_description" } envelope: invalid_request, invalid_client, invalid_grant, unsupported_grant_type, invalid_scope.
Status codes
The edge bot gate (403 {"error":"Forbidden"})
Before any handler runs, the edge middleware refuses /api/* requests whose User-Agent looks like a generic script or crawler (curl/, wget, python-requests, go-http, java/, ruby, php/, most crawler UAs) — or is missing / shorter than 10 characters — with a bare 403 {"error":"Forbidden"}. Two ways through it:
- Send a
wm_…API key inX-WorldMonitor-Key(orX-Api-Key) — a well-formed key bypasses the gate before the UA is examined. - Send a browser-like
User-Agentfor anonymous reads (e.g.curl -A "Mozilla/5.0 (compatible; my-integration/1.0)" …).
- Exact bot-gate bypass paths: intentionally public
/api/version,/api/health,/api/llms.txt,/api/product-catalog, and/api/download.md; authenticated machine routes/api/seed-contract-probe(requiresx-probe-secret: $RELAY_SHARED_SECRET) and/api/internal/brief-why-matters(requiresAuthorization: Bearer $RELAY_SHARED_SECRET) also bypass only this User-Agent filter. - Method-aware
GET/HEADAPI markdown twins: valid requests for/api/**/*.mdbypass the gate; other methods do not inherit that exception. - Recognized social preview UAs may fetch
/api/storyand/api/og-story; recognized social image UAs may fetch.pngpaths and valid signed brief-carousel route shapes.
/api/* paths — including anonymous public reads like GET /api/bootstrap?public=1 — remain behind the gate. That is why a bare curl of a documented anonymous endpoint can return 403 while the same URL works from a browser.
Reading X-Billing-Verification
On JSON gateway surfaces, X-Billing-Verification generally mirrors the response body’s billing code. The Pro-MCP OAuth flow deliberately has two response shapes: its grant-handshake endpoints use TIER_VERIFICATION_UNAVAILABLE for retryable verification failures and INSUFFICIENT_TIER for genuinely insufficient tier states, while /oauth/authorize-pro renders HTML. A provider-confirmed lapse follows the free-account OAuth path and receives a restricted, metered token instead of either denial. The header is listed in Access-Control-Expose-Headers, so browser clients can read it cross-origin. Branch on it rather than on status alone: a 503 from these surfaces can also mean “required env not configured”, which is not retryable, while other API handlers may still emit terminal subscription_lapsed responses.
Where subscription_lapsed is emitted by a non-OAuth handler or by the rare MCP race in which coverage ends during a Pro call, it is terminal and carries no Retry-After; renewal, not retry, is the response. At the OAuth grant-handshake endpoints, a lapse already confirmed at the shared pre-check is instead admitted as a free account. Treat INSUFFICIENT_TIER as terminal even when there is no billing header, and TIER_VERIFICATION_UNAVAILABLE as retryable.
Generated RPC billing denials
Generated RPC handlers preserve the same billing decision in their native error shape.summarizeArticle reports errors inside a successful RPC envelope, so a retryable billing state uses status: SUMMARIZE_STATUS_ERROR, errorType: ServiceError, and the billing code in statusDetail; a provider-confirmed lapse uses errorType: AuthError. The scenario, shipping-v2, and forecast-simulation handlers use generated ApiError exceptions instead, so retryable states surface as HTTP 503 with Retry-After, X-Billing-Verification, and the same body code. A confirmed free caller still receives the existing Pro-required 403.
Common error strings
Idempotency-Key
All generated OpenAPI POST operations and these standalone write endpoints accept an optionalIdempotency-Key request header: POST /api/create-checkout, POST /api/customer-portal, POST /api/notify, POST /api/user-prefs, and POST /api/notification-channels. Use a client-generated key for any POST that your client may retry after a network timeout or retryable 5xx.
Retrying a POST with the same key and an identical request body replays the original completed response instead of re-executing the operation. The replay contract reproduces the original status, body, and Content-Type; success responses echo Idempotency-Key and set Idempotent-Replayed: false on the first response or Idempotent-Replayed: true on replay. Keys are scoped per authenticated caller, fall back to the source IP for unauthenticated endpoints, and are retained for 24 hours after a completed response unless the endpoint documents a shorter replay window.
If the first request is still running, the retry returns 409 idempotency_conflict with Retry-After: 2; retry after that delay with the same key and identical body. If the same key is reused with a different request body, the API returns 422 idempotency_key_reused; do not retry unchanged, because the client must either send the original body or choose a new key for the new operation.
For mutations this avoids duplicating the side effect, including async enqueues such as POST /api/scenario/v1/run-scenario. For batch-read POSTs, replay returns the cached snapshot and that snapshot can be up to 24 hours stale. A 409 idempotency_conflict means the original keyed request is still running and keeps its in-flight lock until it completes. If the original execution itself returns a retryable status (408, 409, 429, or 5xx), that response is not cached and the processing lock is released, so a later retry may re-execute the operation and should only be sent when the endpoint contract is safe for that retry or the client can tolerate re-execution.
Retry strategy
Retry-After is authoritative — never retry earlier than it asks. When a response carries the header, wait exactly that long; it replaces the backoff schedules below rather than racing them. Retrying sooner is not merely impolite here: on a billing-verification 503 the server briefly caches the transient answer per caller, and that cache window sits just inside the delay it advertises. An early retry is therefore served the identical failure it just received, spending quota on an attempt that cannot succeed. Against entitlement_verification_unavailable (fixed Retry-After: 5), a generic 1s/2s/4s schedule wastes its early attempts inside that window and only its third can succeed — where one request sent after the advertised delay would have. Tight client-side loops fare worse still: three attempts inside two seconds all land in the same cached failure.
Idempotent reads (GET): retry 429/5xx honoring Retry-After; when it is absent, use exponential backoff (1s, 2s, 4s, cap 30s, 5 attempts). Most GET responses are cached at the edge, so the retry usually goes faster.
Writes: send Idempotency-Key on any POST you may retry. Never auto-retry most 4xx responses; the exception is 409 idempotency_conflict, which means a keyed request is still in flight and can be retried after Retry-After: 2 with the same key and identical body. 5xx responses are not cached for replay even when a key is present; retry only when the endpoint contract is safe for a repeated execution or the client can tolerate that possibility — honoring Retry-After when present, and otherwise backing off exponentially. A billing-verification 503 is safe to replay on this point: the entitlement gate answers before the handler runs, so no side effect has been applied. Without a key, inspect the endpoint contract before retrying because an unkeyed repeat can duplicate the side effect.
MCP: the server returns tool errors in the JSON-RPC result with isError: true and a text explanation — those are not HTTP errors. Handle them at the tool-call layer.
Debugging
- Every edge response includes
x-vercel-idandx-worldmonitor-deployheaders — include those when reporting issues. - Sentry alerts forward to status.worldmonitor.app.
GET /api/healthandGET /api/seed-healthshow per-seed freshness; a stale seed is the most common root cause of unexpected empty payloads.