Error Handling

Endpoint schemas and parameter details live in the API Reference. This page covers shared error behavior — the format, the status-code classes, and the anti-oracle pattern that shapes how errors are returned.

Problem Details

Literal error responses use Problem Details with Content-Type: application/problem+json, following RFC 9457.

Every error response includes:

Field	Type	Description
`type`	string (URI)	Machine-readable error identifier. Always follows the pattern `https://api.literal.so/errors/{ERROR_CODE}`.
`title`	string	Human-readable summary derived from the error code in title case — e.g. `INVALID_REQUEST` → `"Invalid Request"`.
`status`	integer	HTTP status code.
`code`	string	Machine-readable error code — use this for programmatic error handling.
`instance`	string (opt)	The request path that triggered the error.

Example:

{
  "type": "https://api.literal.so/errors/INVALID_REQUEST",
  "title": "Invalid Request",
  "status": 400,
  "code": "INVALID_REQUEST",
  "instance": "/v1/documents"
}

Handling Error Classes

Use these classes for client-side handling. For endpoint-specific codes, see the API Reference.

400 Bad Request

The request is malformed or failed validation. Fix the request before retrying.

401 Unauthorized

The session is missing, expired, or invalid. Refresh the access token via /auth/tokens/refresh. If refresh fails, re-authenticate from login. Locked sessions also return 401 with a code indicating the session must be unlocked through the appropriate token submission — see Session Lifecycle.

403 Forbidden

The session is valid, but the caller lacks the required role or permission. CSRF-protected endpoints also return 403 if the required X-Literal-Request: 1 header is missing. See Authentication.

404 Not Found

The route does not exist, the resource does not exist, or the caller is not authorized to access it. For sensitive resource lookups, missing and unauthorized cases collapse to the same response — see Anti-Oracle Behavior below.

409 Conflict

The resource is in a conflicting state, or the operation violates a constraint. Check the code field for the specific conflict and fetch the current state before retrying.

413 Payload Too Large

Document upload exceeds the 100 MB size limit. Reduce file size before encrypting and uploading.

415 Unsupported Media Type

The Content-Type header is missing or not supported. Use application/json for JSON requests or application/octet-stream for binary uploads.

429 Too Many Requests

The rate limit was exceeded. Read the Retry-After response header and back off exponentially. See Rate Limiting.

500 / 503

Unexpected server error or upstream dependency unavailable. Retry with exponential backoff. If the error persists, contact support.

Anti-Oracle Behavior

For sensitive resource lookups, Literal avoids revealing whether a resource exists but is inaccessible. Missing and unauthorized resources return the same 404 Not Found shape where this behavior applies.

This prevents callers from probing document, grant, entity, or token-backed relationships to learn what exists.

Client applications should not rely on distinguishing "missing" from "not authorized" for sensitive resources. Treat both as unavailable to the caller.

Related privacy-preserving patterns include:

OPRF challenge responses avoid revealing whether a login identifier is registered.
Grant discovery returns ambiguous view-tag matches instead of confirming a specific recipient.
Blind routing replaces plaintext relationship lookups with token equality.

See Blind Routing for the underlying privacy model.

Status Code Summary

Status	When you’ll see it	What to do
`400`	Request body or query params fail schema validation.	Fix the request against the endpoint schema.
`401`	Token missing, expired, revoked, or session locked.	Refresh via `/auth/tokens/refresh`. If that fails, re-authenticate.
`403`	Valid token, but insufficient permissions or missing CSRF header.	Check role and required headers.
`404`	Route, resource, or sensitive resource not authorized for the caller.	Check the URL path and authorization.
`409`	Duplicate resource or invalid state transition.	Check the `code` field and fetch current state before retrying.
`413`	Upload exceeds 100 MB.	Reduce file size before encrypting.
`415`	Wrong or missing `Content-Type`.	Use `application/json` or `application/octet-stream`.
`429`	Rate limit exceeded.	Read `Retry-After` header. Back off.
`500`	Unexpected server error.	Retry with exponential backoff. If persistent, contact support.
`503`	Upstream dependency temporarily unavailable.	Retry with exponential backoff. If persistent, contact support.