Errors, rate limits, and idempotency

The full error code registry, rate-limit headers, and idempotency rules for the Platform API.

Reference for the SideShift OAuth API (/api/oauth/v1): the error envelope, the stable error-code registry, the WWW-Authenticate challenge, protocol-endpoint errors, rate-limit policy + headers, and idempotency.

New to the API? Start with OAuth quickstart (register, authorize, get a token) and workflows.md (end-to-end recipes). The machine-readable contract is openapi.yaml.

---

1. Error envelope (resource endpoints)

Every error from a resource endpoint (campaigns, contracts, creators, applications, posts, payouts, invoices, messages, webhooks, settings, invites) is returned as a structured JSON envelope:

{
  "error": {
    "code": "insufficient_scope",
    "message": "Requires scope 'campaigns:write'",
    "requestId": "req_8f1c2e9a4b7d"
  }
}

• code - a stable machine-readable code from the registry. Branch on this, never on message.
• message - a human-readable explanation. Wording may change; it is for logs and humans, not control flow.
• requestId - a req_… correlation id. Always include it when contacting support so we can find the exact request in our logs.
• meta - an optional object with structured context (e.g. the missing scope, the conflicting field). Present only when useful; treat it as additive.

The HTTP status line always matches code (see the table below).

---

2. Error code registry

These are the only codes a resource endpoint emits. Status is fixed per code (single source of truth: lib/api/core/errors.ts).

Code	HTTP	Meaning
invalid_request	400	Malformed request or failed validation (bad body, missing field, bad query param).
unauthorized	401	Bearer access token is missing, expired, or revoked. Re-authenticate.
subscription_required	402	The token’s company tenant does not have an active subscription.
insufficient_scope	403	Valid token, but it does not carry the scope this operation requires. Re-authorize with the scope.
forbidden	403	The action is never permitted for this grant, regardless of scope - see below.
not_found	404	The resource does not exist or belongs to another tenant (see below).
conflict	409	A state conflict (e.g. voiding an already-paid invoice).
idempotency_conflict	409	An Idempotency-Key was reused with a different request body. See §6.
rate_limited	429	Too many requests for this (client, company). See §5.
internal	500	An unexpected server error. Safe to retry idempotent requests with backoff.

unauthorized vs insufficient_scope vs forbidden

These three are routinely confused. They are distinct:

• unauthorized (401) - the credential itself is bad: no Authorization header, an expired access token (1h TTL), or a revoked token. The fix is to re-authenticate (refresh the token, or restart the authorization flow).

• insufficient_scope (403) - the token is valid but was not granted the scope this call needs (e.g. you hold campaigns:read and called POST /campaigns, which needs campaigns:write). The fix is to re-authorize, requesting the missing scope on the consent screen. The response carries a WWW-Authenticate header naming the required scope.

• forbidden (403) - the action is never allowed for this grant, no matter what scope you add. This is a hard policy/capability block, e.g.:

  • a sandbox / test-mode grant attempting a money-moving or external side-effect write (payouts execute / Quick Pay, invoice create/send/void, sending a message); or
  • a policy block that is provably not cross-tenant (e.g. invoicing not available for the account, account too new).

  Re-authorizing will not fix a forbidden. Example body: "payouts:write is not available for sandbox (test-mode) grants".

Cross-tenant access is always not_found (404), never forbidden

A token is bound to exactly one company tenant. If you request a resource id that belongs to another company, the API returns 404 not_found - the same response as a genuinely nonexistent id. It is never 403. This is deliberate: you cannot use the status code to probe whether another company’s resource exists. 403 forbidden is reserved for the in-tenant policy/capability blocks described above.

---

3. WWW-Authenticate

On a 401 unauthorized and on a 403 insufficient_scope, the response carries an RFC 6750 / RFC 9728 WWW-Authenticate: Bearer … challenge that tells the client what to do:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="campaigns:write", resource_metadata="https://app.sideshift.app/.well-known/oauth-protected-resource"
Content-Type: application/json

• error - the OAuth error (invalid_token / insufficient_scope).
• scope - the scope the client must request to perform this operation. Read it, add it to your next authorization request, and have the user re-consent.
• resource_metadata - the URL of the protected-resource metadata document (RFC 9728), which lists the authorization server and supported scopes for discovery.

A plain 403 forbidden (the hard policy block) does not carry a WWW-Authenticate header - there is no scope that would grant access.

---

4. Protocol endpoint errors (RFC 6749)

The auth-server endpoints - /register, /authorize, /token, /revoke, /clients/{id} - are not resource endpoints. They follow OAuth conventions and return the RFC 6749 error body instead of the envelope:

{ "error": "invalid_grant", "error_description": "Authorization code is invalid or expired" }

Common error values:

error	Where / HTTP	Meaning
invalid_request	400	Missing/duplicated/malformed parameter.
invalid_client	401	Client authentication failed (token/revoke) or the registration access token is invalid (/clients/{id}). Carries a WWW-Authenticate (Basic or Bearer) challenge.
invalid_grant	400	Authorization code or refresh token is invalid, expired, revoked, or reused.
unauthorized_client	400	The client may not use this grant type.
unsupported_grant_type	400	grant_type is not one we support.
invalid_scope	400	Requested scope is unknown or not allowed for the client.
invalid_redirect_uri	400	redirect_uri is missing or does not exactly match a registered URI.
invalid_client_metadata	400	A field in a /register (or /clients/{id} update) request is invalid.
temporarily_unavailable	429	Rate-limited (per-IP or per-client). See §5.

subscription_required is a resource API error, not a protocol or token-endpoint error. A client can finish consent and receive tokens while its company subscription is inactive, but protected resource calls return 402 until the subscription is active.

/authorize is special: when the client_id/redirect_uri cannot be trusted it renders an HTML error page (400) rather than redirecting; otherwise recoverable errors come back as a redirect to redirect_uri carrying error, error_description, state, and iss.

Consent endpoints (/consent)

The in-session consent bridge is not an RFC 6749 endpoint. It uses a small { "error", "message" } body, where error is one of: invalid_request (400), unauthorized (401), subscription_required (402), forbidden / csrf (403), not_found (404), already_used (409), or expired (410).

---

5. Rate limits

Limits are per rolling 60-second window, scoped by subject. Source of truth: lib/api/oauth/rate-limit.ts.

Surface / endpoint	Limit	Scope (subject)
Resource endpoints (all of /api/oauth/v1/*)	600 / min	per (client, company)
POST /register	20 / min	per IP
GET /authorize	60 / min	per IP
POST /token	120 / min	per client
POST /token (unauthenticated)	60 / min	per IP (when no/failed client auth)
POST /revoke	120 / min	per client

Because the resource limit is per (client, company), one misbehaving client cannot exhaust the budget of a tenant it shares with other clients.

Headers

Every response carries the current window state:

Header	Value
X-RateLimit-Limit	Max requests allowed in the window.
X-RateLimit-Remaining	Requests remaining in the window (never below 0).
X-RateLimit-Reset	Window reset time, epoch seconds.

A 429 response (rate_limited envelope, or temporarily_unavailable on the protocol surface) additionally carries:

Header	Value
Retry-After	Seconds to wait before retrying.

Handling 429

Honor Retry-After: wait at least that many seconds, then retry with exponential backoff and jitter for repeated failures. Proactively, watch X-RateLimit-Remaining and throttle yourself before you hit zero rather than hammering until you get a 429.

---

6. Idempotency

Every mutating resource endpoint (POST / PATCH / PUT) accepts an Idempotency-Key request header. The key is client-chosen - use a fresh UUID per logical operation.

Semantics:

• Replay (same key + same body) → the original stored response is returned (same status + body). Safe to retry after a network timeout without double-applying the operation.
• Same key + a different body → 409 idempotency_conflict. A key is bound to the first request body it saw.
• Keys are retained for roughly 24 hours, then forgotten.

Strongly recommended for money-moving calls

Always send an Idempotency-Key on calls that move money or fire external side effects - POST /payouts/execute, POST /payouts/quick-pay, and the invoice writes (POST /invoices, /invoices/{id}/send, /invoices/{id}/void). For the payout endpoints the key is required (a request without one is rejected 400); it is the sole double-pay guard for Quick Pay. The key is also required by POST /campaigns/{id}/analytics-history so a retried multi-store import cannot apply a second logical batch; that endpoint enforces an 8–200 character key length.

Note these same endpoints are also rejected with 403 forbidden for sandbox / test-mode grants (see §2) - test-mode tokens cannot move real money or fire real external effects.

Example

curl -sS -X POST https://app.sideshift.app/api/oauth/v1/payouts/quick-pay \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "email": "[e-mail]", "amount": 100, "notes": "Thanks!" }'

Reuse the same Idempotency-Key value when retrying that exact request after a timeout; generate a new one for a genuinely new payment.

---

See also: OAuth quickstart · workflows.md · openapi.yaml.