Errors and status codes

Simkl uses standard HTTP status codes. Almost every error body carries error (machine-readable identifier), code (integer — the HTTP status code echoed in the body), and an optional message (human-readable guidance).

Standard error envelope

{
  "error":   "client_id_failed",
  "code":    412,
  "message": "Your client_id is wrong. Try another one"
}

The /oauth2/* endpoints use a different envelope. They follow RFC 6749 §5.2 instead: an error plus an optional error_description, and no code field — the HTTP status carries that on its own.

RFC 6749 envelope — /oauth2/token, /oauth2/device, /oauth2/revoke

{
  "error":             "invalid_grant",
  "error_description": "PKCE verification failed"
}

This is what stock OAuth libraries expect, which is the point. It applies only to paths beginning /oauth2/ — an AUTH V2 token used on a normal API endpoint still gets the standard envelope above. If your error handler reads code from the body, it will find nothing on these four endpoints; read the HTTP status instead.Full list: OAuth 2.0 errors.

Branch on error, never on message. The error identifier is the contract — it’s stable across releases. The message text is developer-facing prose that may be reworded at any time. Parsing message will break your client.

At a glance

Code	Name	Retry?
`200`	OK	—
`201`	Created	—
`204`	No Content	—
`302`	Found	—
`400`	Bad Request	No — fix the request
`401`	Unauthorized	No — re-authenticate
`403`	Forbidden	No — fix the app or contact us
`404`	Not Found	No
`409`	Conflict	No
`412`	client_id failed	No
`429`	Too Many Requests	Yes — back off
`500`	Internal Server Error	Yes — exponential backoff
`502`	Bad Gateway	Yes — exponential backoff
`503`	Service Unavailable	Yes — exponential backoff

Getting a token is scored separately. The four /oauth2/* endpoints return their own OAuth-standard error vocabulary in a different envelope — including three values in the device flow that are not failures at all. See OAuth 2.0 errors.

Not every endpoint can return every code. Each endpoint’s reference page lists the codes that actually fire there — many endpoints can only return a subset (e.g., /sync/activities can only return 200, 401, 412, 429, 500). The 4xx/5xx pages below describe the codes; check the per-endpoint reference for which apply.

Success codes

OK

200 — Success. The body contains the resource you requested.

Created

201 — Success. A new resource was created. Typical for POST /sync/... and POST /scrobble/....

No Content

204 — Success but the response body is empty. Typical for DELETE endpoints.

Found

302 — A redirect. Follow the Location header. Most commonly returned by the redirect endpoint.

4xx — your request

Bad Request

400 — The request was malformed. The message field usually identifies the offending parameter. Real error values returned

`error`	When	Example `message`
`empty_field`	A required field is missing	`Missed "to" parameter`
`wrong_parameter`	A field has an unaccepted value	`Wrong "to" parameter`
`unauthorized_client`	A V2 `client_id` was sent to an AUTH V1 endpoint	`This client_id is an OAuth 2.0 app: use POST /oauth2/token`

Fix Read message, correct the request, then resend. Don’t retry without changing the request.

400 Bad Request

{
  "error":   "empty_field",
  "code":    400,
  "message": "Missed \"to\" parameter"
}

`unauthorized_client` — a V2 app on a V1 endpoint

400 Bad Request

{
  "error":   "unauthorized_client",
  "code":    400,
  "message": "This client_id is an OAuth 2.0 app: use POST /oauth2/device instead of /oauth/pin"
}

Your client_id is registered for AUTH V2, and you sent it to an AUTH V1 endpoint. It is returned by GET /oauth/pin, POST /oauth/token, GET /oauth/authorize and the account-link endpoint, and the message names the V2 endpoint to use instead. This is the exact mirror of oauth2_token_required: that one is a V1 token on a V2 endpoint, this one is a V2 client ID on a V1 endpoint. A V2 registration is V2-only, in both directions — there is no mixed mode.

If you are running both registrations side by side, this is the error that tells you they got crossed. Each client_id must go to its own endpoints: V1 credentials to /oauth/*, V2 credentials to /oauth2/*. The usual cause is a shared config that resolves one client_id while the flow code still points at the other version’s URLs.

Unauthorized

401 — Missing or invalid user access token. Common causes

Authorization header missing on a token-required endpoint.
The user’s access_token was revoked at Connected Apps settings.
A typo or truncation in the token value.

Fix Re-authenticate. What that means depends on which auth version your app uses. For AUTH V1, tokens advertise expires_in: 157680000 (5 years) on mint, so a 401 in practice means the user removed your app from their account, or the token never matched in the first place. Send them through the flow again. For AUTH V2, access tokens last 7 days, so a 401 is usually just expiry. Try the refresh grant first and only re-authorize if the refresh also fails. Sending a user through consent for a routine expiry is avoidable.

401 Unauthorized

{
  "error": "user_token_failed",
  "code":  401
}

The 401 response also carries an RFC 6750 §3 WWW-Authenticate header for clients that key off it:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
WWW-Authenticate: Bearer realm="api.simkl.com", error="user_token_failed"

AUTH V2 tokens report invalid_token rather than user_token_failed when the access token is unrecognised or past its 7-day expiry. Handle both — which one you see depends on the token’s generation, not on what went wrong.

401 Unauthorized

{
  "error":   "invalid_token",
  "code":    401,
  "message": "Access token has expired"
}

Note that the WWW-Authenticate challenge above is sent on normal API endpoints only. A 401 from /oauth2/* itself does not carry a Bearer challenge — there is no bearer token involved in getting one. The exception is a failed client_secret sent via HTTP Basic, which answers with WWW-Authenticate: Basic realm="oauth2".

`user_token_required` — a different 401

401 Unauthorized

{
  "error":   "user_token_required",
  "code":    401,
  "message": "This client_id requires a user access token on every request"
}

This is not an expired or rejected token — it means the request arrived with no token at all, on an endpoint that requires one. AUTH V2 apps see this wherever V1 apps could use a bare client_id, because V2 limits anonymous access to public catalog data: movie, show and anime summaries by Simkl ID, episode lists, and the Trending and Calendar data files. Everything else needs a token, search included. Refreshing will not help, because nothing was wrong with your token. Check that the code path actually attaches the Authorization header — it is usually a browse or search screen written before sign-in was required. Search is the common one, since fetching a known title by ID nearby still works and makes the failure look inconsistent. If you see this on an app you believe should allow anonymous access, the app is configured to require a user token; get in touch rather than working around it.

Forbidden

403 — Refused. The request was understood but the caller is not permitted to perform it. Known error values

`error`	When
`insufficient_scope`	An AUTH V2 token without `media:write` attempted a write
`oauth2_token_required`	An AUTH V1 token was sent to an endpoint that requires AUTH V2 — currently Custom Lists
`private_list`	The custom list exists but the caller is not its owner or a collaborator
`redirect_failed`	OAuth/PIN `redirect` parameter doesn’t match a URL registered for your app
`forbidden`	Generic refusal — feature gated to Simkl PRO/VIP, or an action the user hasn’t consented to

Fix Match the redirect URL exactly to what’s registered in your developer settings. For PRO/VIP-gated features, surface an upgrade prompt rather than retrying.

`insufficient_scope` — the token cannot write

403 Forbidden

{
  "error":   "insufficient_scope",
  "code":    403,
  "message": "This action requires the \"media:read media:write\" scope"
}

The token is valid and the user is signed in — it was just minted without write access. The response also names the scope you needed, in an RFC 6750 §3.1 header:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="media:read media:write"

Refreshing will not fix this, and neither will asking for a wider scope on the refresh — a grant’s scope can never widen. The user has to authorize again with media:read media:write on the authorize URL. Nearly always this traces back to one of the two traps on Scopes: the scope parameter was omitted (which grants read-only), or media:write was misspelled or miscased and silently ignored. Check what the token response’s scope field actually said at mint time. If the token really does hold media:write, or the failing call is a plain read, check whether your client attached a request body to a GET — that counts as a write regardless of the endpoint.

`oauth2_token_required` — your token is the wrong generation

403 Forbidden

{
  "error":   "oauth2_token_required",
  "code":    403,
  "message": "Custom Lists require an OAuth 2.0 access token"
}

Nothing is wrong with the token — it is a valid V1 token being sent to an endpoint that only accepts V2. Re-authorizing the same V1 app will not fix it; the user has to authorize your AUTH V2 registration, which is a different client_id. See Migrating from V1 to V2. Note it is a 403, not a 401 — the request authenticated fine, it just is not permitted here. Do not send it down your token-refresh path.

403 Forbidden — redirect mismatch

{
  "error":   "redirect_failed",
  "code":    403,
  "message": "Invalid redirect_uri. This value must match a URL registered with the API Key."
}

Not Found

404 — The URL or resource doesn’t exist.

Most catalog endpoints don’t return 404 for missing IDs. Hitting /movies/99999999 returns 200 [] (empty array), not 404. Use 404 documentation in per-endpoint references as the source of truth — most read-only catalog endpoints simply return empty.

404 Not Found

{
  "error": "id_err",
  "code":  404
}

Conflict

409 — The resource state conflicts with the request. Common causes

Tried to POST /scrobble/stop on a session that completed in the last hour.
Tried to perform a write that would duplicate an existing record.

Fix Treat 409 as soft-success when scrobbling — the user already finished the episode. Don’t retry the same call. The body includes watched_at (when the original watch landed) and expires_at (when the 1-hour duplicate-window closes), so you can show the user the existing watch state instead of re-firing the call.

409 Conflict (POST /scrobble/stop)

{
  "error":      "already_watched",
  "watched_at": "2026-05-08T14:00:00Z",
  "expires_at": "2026-05-08T15:00:00Z"
}

client_id failed

412 — Your client_id is missing, wrong, or suspended — or a throttling block is still active. Common causes

Typo in client_id (use the value from developer settings, not a screenshot).
App was suspended for a Terms of Service violation.
Repeatedly exceeding the 1-POST-per-second cap, which places a temporary throttling block on the offending token or client_id. Further overages extend it.

Fix Double-check the value. If it’s correct, you are most likely throttled: stop, wait, and reduce your write rate before trying again. If it persists, reach out on Discord.

Running out of your daily quota does not produce this. That returns 429 with user_limit_exceeded or app_limit_exceeded. A 412 means the request is wrong, or that you are already blocked — either way, retrying it unchanged will not help. See Rate limits.

412 client_id failed

{
  "error":   "client_id_failed",
  "code":    412,
  "message": "Your client_id is wrong. Try another one"
}

Too Many Requests

429 — You sent too many requests. Two different limits produce this status, and they need opposite responses, so read the body before deciding how long to wait.

Body	Which limit	Fix
`rate_limit`	The per-second rate — 10 GET/sec, 1 POST/sec.	Clears in about a second. Pause briefly and continue; exponential backoff is overkill.
`user_limit_exceeded`	That user’s daily allowance (AUTH V2).	Read `Retry-After` and wait for the window. Only that user is affected.
`app_limit_exceeded`	Your app’s daily allowance (AUTH V1).	Same, but every one of your users is affected at once.

Fix Do not use exponential backoff on the daily ones. The quota resets at midnight US Eastern, so retrying over seconds cannot clear it — read Retry-After, which carries the exact seconds remaining, or stop and tell the user. On rate_limit, the opposite: it clears almost immediately, so a long backoff just makes your app feel broken. To avoid both: cache responses aggressively, use the Trending and Calendar CDN files instead of polling, batch writes into arrays rather than sending them one at a time, and keep one request in flight at a time on uncached endpoints. Full guidance: Rate limits.

400 with {"error": "RATE_LIMIT"} is a different thing entirely, despite the name. It is a short per-user write lock meaning your previous write for that user is still running. Serialise your writes for that user and retry in a moment — do not back off for minutes, and do not retry in parallel.

429 Too Many Requests

{
  "error": "rate_limit",
  "code":  429
}

OAuth 2.0 errors — `/oauth2/*`

These are the errors from the four AUTH V2 endpoints themselves, not from API calls made with the resulting token. They use the RFC 6749 envelope described at the top — error plus an optional error_description, with no code field.

`POST /oauth2/token`

`error`	HTTP	When
`invalid_client`	`401`	Unknown or missing `client_id`, a V1 `client_id`, or a Server apps & services app whose `client_secret` is missing or wrong
`invalid_request`	`400`	A required parameter for the grant is absent — `code`, `code_verifier` or `device_code`
`invalid_grant`	`400`	The grant itself was rejected: code expired, already used, or issued to another client; PKCE verification failed; `redirect_uri` does not match the authorization request; refresh token invalid, expired, or issued to another client
`invalid_scope`	`400`	A refresh asked for wider scope than the original grant
`unsupported_grant_type`	`400`	`grant_type` is not one of the three supported values. `client_credentials` lands here — there is no app-only grant
`authorization_pending`	`400`	Device flow: the user has not approved yet. Keep polling
`slow_down`	`400`	Device flow: you polled faster than `interval`. Add 5 seconds and wait
`expired_token`	`400`	Device flow: the `device_code` is invalid or past its 15 minutes. Start over

The three device-flow values are not failures. authorization_pending and slow_down are the normal shape of a polling loop, and only expired_token ends it. Treating any 400 from this endpoint as fatal is the most common way to break the device flow.

invalid_grant is deliberately vague, and it is the one you will hit most. A wrong verifier, a replayed code and an expired code all return the same error — the endpoint will not tell you which, because distinguishing them would help an attacker probe codes.Debug it by elimination: check the code is under 10 minutes old and used only once, then verify your PKCE pair against the RFC test vector, then compare redirect_uri byte for byte with the one you sent to /oauth2/authorize.

`POST /oauth2/device` and `POST /oauth2/revoke`

`error`	HTTP	When
`invalid_client`	`401`	Unknown or missing `client_id`, or a V1 `client_id`. `/oauth2/device` needs no secret; `/oauth2/revoke` does, for a Server apps & services app

Otherwise revoke always succeeds. An unknown, already-revoked or foreign token returns 200 with an empty body, per RFC 7009 §2.2 — never treat a 200 here as proof the token existed.

`GET /oauth2/authorize`

The consent page is a browser destination, so its failures are not JSON for your code to parse. They split by whether Simkl can trust where it would send the user:

Problem	What happens
`client_id` unknown, or `redirect_uri` not registered	An error page renders and Simkl never redirects — the open-redirect defence. Nothing reaches your callback
`code_challenge` missing, or a method other than `S256`	Redirects back with `error=invalid_request` and your `state`
The user declines	Redirects back with `error=access_denied` and your `state`

Both redirect cases also carry iss. Validate state on the error path exactly as you would on success, and treat an unrecognised error value the same as access_denied rather than special-casing it.

5xx — our problem

Internal Server Error

500 — Something broke on our side. Fix Retry with exponential backoff. If the error persists for more than ~30 seconds, report it on Discord.

500 Internal Server Error

{
  "error": "internal",
  "code":  500
}

Bad Gateway

502 — Simkl is being upgraded or briefly unreachable. Fix Retry with exponential backoff. Check status for known issues.

Service Unavailable

503 — Servers are up but overloaded. Fix Retry after the delay. Respect any Retry-After header.

Handling errors gracefully

Exponential backoff

Recommended retry pattern for genuinely transient errors (500, 502, 503). A 429 needs its own handling — see Too Many Requests above, since only the per-second kind is worth retrying:

Attempt	Wait before retry
1	1 s
2	2 s
3	4 s
4	8 s
5	16 s (give up after this)

Add jitter (random 0–1 s) so multiple clients don’t synchronize.

retry-with-backoff.js

async function retry(fn, attempts = 5) {
  for (let i = 0; i < attempts; i++) {
    try {
      return await fn();
    } catch (err) {
      if (i === attempts - 1) throw err;

      // A 429 carrying rate_limit is the per-second cap. It clears in about a
      // second, so wait out the window once rather than backing off.
      if (err.status === 429 && err.body?.error === 'rate_limit') {
        await new Promise((r) => setTimeout(r, 1000 + Math.random() * 250));
        continue;
      }

      // The daily 429s (user_limit_exceeded / app_limit_exceeded) are NOT
      // retried: the quota resets at midnight US Eastern, so backing off for
      // seconds cannot clear it. Honour Retry-After instead.
      if (![500, 502, 503].includes(err.status)) throw err;

      const delay = Math.min(1000 * 2 ** i, 60000) + Math.random() * 1000;
      await new Promise((r) => setTimeout(r, delay));
    }
  }
}

Don’t retry deterministic errors

400, 401, 403, 404, 409, 412 mean something is wrong with the request itself. Retrying without changing the request just wastes quota and triggers 429.

User-facing messaging

message is human-readable but written for developers. For end users:

Code	Suggested user message
`401`	Please sign in again to continue.
`403`	This action isn’t available for your account.
`404`	We couldn’t find that title.
`429`	Slow down — try again in a moment.
`5xx`	Simkl is having a moment. We’ll retry automatically.

Logging

Always log error and code together with your request URL. error is the stable contract you’ll branch on; code confirms the HTTP class.

Get started

Authentication

Conventions

Guides

API Debug

Resources

Errors and status codes

At a glance

Success codes

OK

Created

No Content

Found

4xx — your request

Bad Request

`unauthorized_client` — a V2 app on a V1 endpoint

Unauthorized

`user_token_required` — a different 401

Forbidden

`insufficient_scope` — the token cannot write

`oauth2_token_required` — your token is the wrong generation

Not Found

Conflict

client_id failed

Too Many Requests

OAuth 2.0 errors — `/oauth2/*`

`POST /oauth2/token`

`POST /oauth2/device` and `POST /oauth2/revoke`

`GET /oauth2/authorize`

5xx — our problem

Internal Server Error

Bad Gateway

Service Unavailable

Handling errors gracefully

Exponential backoff

Don’t retry deterministic errors

User-facing messaging

Logging

​At a glance

​Success codes

​OK

​Created

​No Content

​Found

​4xx — your request

​Bad Request

​unauthorized_client — a V2 app on a V1 endpoint

​Unauthorized

​user_token_required — a different 401

​Forbidden

​insufficient_scope — the token cannot write

​oauth2_token_required — your token is the wrong generation

​Not Found

​Conflict

​client_id failed

​Too Many Requests

​OAuth 2.0 errors — /oauth2/*

​POST /oauth2/token

​POST /oauth2/device and POST /oauth2/revoke

​GET /oauth2/authorize

​5xx — our problem

​Internal Server Error

​Bad Gateway

​Service Unavailable

​Handling errors gracefully

​Exponential backoff

​Don’t retry deterministic errors

​User-facing messaging

​Logging

At a glance

Success codes

OK

Created

No Content

Found

4xx — your request

Bad Request

`unauthorized_client` — a V2 app on a V1 endpoint

Unauthorized

`user_token_required` — a different 401

Forbidden

`insufficient_scope` — the token cannot write

`oauth2_token_required` — your token is the wrong generation

Not Found

Conflict

client_id failed

Too Many Requests

OAuth 2.0 errors — `/oauth2/*`

`POST /oauth2/token`

`POST /oauth2/device` and `POST /oauth2/revoke`

`GET /oauth2/authorize`

5xx — our problem

Internal Server Error

Bad Gateway

Service Unavailable

Handling errors gracefully

Exponential backoff

Don’t retry deterministic errors

User-facing messaging

Logging