Skip to main content
REST API documentation

REST API

Error codes

Every error code the API returns, with its HTTP status, what it means and what to do about it.

The error shape

Errors are JSON with this shape. Branch on code, which never changes; message is for people and may change. details lists each invalid field for a 400.

json
{
  "error": {
    "code": "insufficient_scope",
    "message": "Insufficient permissions. Missing scopes: REDLINES_GENERATE",
    "requestId": "0d6f3c1e-8a9b-4f2d-b7e5-91c4a2d3e6f0"
  }
}

Codes

Link to a code directly with its name as the anchor, for example /docs/api/errors#rate_limited.

400invalid_request
The body, query or a header is invalid. details names each problem field. Fix the request; retrying it unchanged fails again.
401api_key_expired
The key has passed its expiry date. Create a new key, or roll the key to get a new secret.
401api_key_revoked
The key was revoked. Create a new key in Settings › Developers.
401invalid_api_key
No key matches. Check that the whole key was copied, or create a new one in Settings › Developers.
401unauthorized
The Authorization header is missing, or it is not the word Bearer followed by the key. Send the key as a Bearer token.
402insufficient_credits
The key owner's AI credits have run out. Top up or upgrade in Attorly, then retry.
402usage_limit_exceeded
An AI usage limit for the key owner or the organization is reached. It resets with the billing period; an organization admin can raise a member's limit.
403forbidden
The key may read the resource but not change it, or the action is not allowed for it. Ask the owner for edit access.
403insufficient_scope
The key lacks a permission this operation needs; the message names it. Create a key with that permission.
403ip_not_allowed
The key has an IP allowlist and the request came from an address outside it. Call from an allowed address, or change the allowlist in Settings › Developers.
403plan_required
The key owner's plan does not include API access, or the owner has left the organization. API access needs Pro or Enterprise.
404not_found
The resource does not exist, or this key cannot see it. Check the id and that the key's owner has access.
405method_not_allowed
The path does not support this HTTP method. The Allow header lists the methods it does.
409conflict
The request conflicts with the resource's current state, for example an action that has already been done. Read the resource and decide again.
409idempotency_request_in_progress
A request with the same Idempotency-Key is still running. Poll the Location header, or retry after Retry-After seconds.
413payload_too_large
The body or the uploaded file is too large. Files can be up to 10 MB.
415unsupported_media_type
The body is in a format this operation does not take. Send JSON, or multipart/form-data where an upload is accepted.
422idempotency_key_reused
The Idempotency-Key was used before for a different request. Use a new key for each distinct request.
422unprocessable
The request is valid but cannot be done, for example an analysis of a document with no governing law chosen. The message says what is missing.
429concurrency_limit_exceeded
Your organization already runs as many long-running AI operations as it may at once. Wait for one to finish, or for the seconds in Retry-After, then retry.
429rate_limited
Too many requests in one of the windows this key counts against. Wait the number of seconds in Retry-After, then retry. The RateLimit header shows which window is full.
500internal_error
Something went wrong at Attorly. Retry with the same Idempotency-Key; if it persists, contact support with the requestId.
504timeout
The operation did not finish in time. Retry with the same Idempotency-Key, or send Prefer: respond-async and poll the operation.