Errors

Public responses follow Problem Details with title, status, detail and, when available, code, suggestion and request_id.

Status	Typical cause	Immediate action
401	Missing, invalid or wrong-environment sk_*	Review the host and secret
409	Invalid reuse of Idempotency-Key	Compare payloads and decide whether the replay was legitimate
422	Schema or business validation failure	Fix the field and avoid blind retries
429	Burst above the limit	Apply exponential backoff with jitter
502	Upstream dependency issue	Retry carefully and keep observability on

Gateway codes

landing_proxy_untrusted

403. The pre-registration origin was not recognized as the official form. Do not call the endpoint directly; restart the flow from the public page.

influencer_gateway_unavailable

503. The pre-registration channel is temporarily unavailable. Retry with backoff and retain the request_id.

idempotency_key_required

400. The mutating operation requires Idempotency-Key. Generate one UUID v4 per business intent and reuse it only when retrying that same operation.

api_key_missing

401. No API key was sent. Use Authorization: Bearer sk_... from your backend or X-API-Key when required by the HTTP client.

api_key_invalid

401. The key does not exist, was revoked, or belongs to another environment. Check its prefix, host, and active rotation in the dashboard.

api_key_auth_unavailable

503. Key validation did not respond. Retry carefully; if it persists, send the request_id to support without sharing the secret.

scope_forbidden

403. The key is valid but lacks the route scope. Adjust the scopes or use another least-privilege key that covers the operation. In the browser, use a publishable key only for explicitly compatible routes; never expose a secret key.

checkout_origin_required

403. The public checkout call did not include a valid browser origin. Open checkout through the hosted domain or the configured custom domain. For server rendering, preserve the forwarded public host; do not invent or overwrite the Origin header.

rate_limit_exceeded

429. The key exceeded its request limit. Honor Retry-After when present and apply exponential backoff with jitter.

idempotency_key_replayed

409. The same key was already reserved for this endpoint. Recover the original response for the same payload or generate a new key for a new intent.

Practical rule

Do not route errors by free-form text. Use status, code and request_id.