Errors
When a request fails, the Glanced API returns JSON you can read, with a code, a message, and a request id to quote to support. Every status code, explained.
Every failed request returns JSON. Most errors share one body.
The error envelope
{
"error": "NOTFOUNDERROR",
"message": "Item not found or access denied",
"details": { "status_code": 404 },
"timestamp": "2026-08-27T09:41:12.315818Z",
"request_id": "8f14e45f-ea1f-4cd1-9a56-31d6a3f0a2c1"
}| Field | Meaning |
|---|---|
error | Machine-readable code, usually the exception class name upper-cased: NOTFOUNDERROR, QUOTAEXCEEDEDERROR, CONFLICTERROR, VALIDATIONERROR (400). Two codes break that pattern: request validation (422) returns VALIDATION_ERROR, with the underscore, and an unexpected server error (500) returns INTERNAL_SERVER_ERROR. |
message | Human-readable description of what went wrong. |
details | Optional payload with error-specific facts. On 402 it carries quota_type, current, and limit. |
timestamp | Server time of the error, in UTC. |
request_id | Correlation id for this request. Include it if you contact support. |
Auth and rate-limit failures
Authentication failures and rate limits return a smaller body instead.
A missing, invalid, or revoked token:
{
"error": "Missing or invalid session",
"status_code": 401
}A rate limit, sent with a Retry-After header in seconds:
{
"error": "Rate limit exceeded",
"message": "Rate limit exceeded. Please try again later.",
"type": "rate_limit"
}You'll see these smaller bodies on 401s, 429s, and some 403s and 503s. Everything else returns the envelope.
Status codes
| Code | When |
|---|---|
| 400 | Something in the request doesn't make sense, like saving notes on an episode or moving a subscription into a folder that doesn't exist. |
| 401 | Missing, invalid, or revoked credentials. |
| 402 | Quota exceeded, or a feature your plan doesn't include. details carries the quota facts when they apply. |
| 403 | A banned or locked account, or a token used on an endpoint outside its allowed scope. |
| 404 | The resource doesn't exist or belongs to another account. |
| 409 | A conflict, like trying to create a folder, tag, or saved search with a name that's already taken. |
| 422 | Request validation failed. message joins one friendly sentence per invalid field. details.validation_errors is present in development environments only. |
| 429 | A rate limit was hit. See Rate limits. |
| 500 | Something broke on our side. Include the request_id if you contact support. |
| 503 | The authentication service was unavailable, or a downstream service failed. |
Each endpoint page declares the errors it can actually return, in its Responses section.
How is this guide?