Errors

Handle AI Glot API failures using stable error codes, request IDs, retry guidance and anchored explanations for every documented error.

Every API failure uses one envelope. Branch on error.code, never on the human-readable message.

Example error{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This credential is missing the batches:write scope.",
    "docs_url": "https://ai-glot.com/docs/api/errors#insufficient_scope"
  },
  "request_id": "req_example"
}

Status codes

Status	Meaning	What to do
400	Malformed request or unknown field	Fix the request
401	Credential missing, invalid, expired or revoked	Replace or renew it
403	Authenticated but not allowed	Grant the required scope or feature
404	Resource absent or outside this workspace	Check the ID and workspace
409	Current state conflicts with the request	Read the resource, then decide
413	Request body too large	Send a smaller body
422	Well-formed but invalid value	Fix the named value
429	Rate limited	Wait for `Retry-After`
500/503	AI Glot failed or is temporarily unavailable	Retry with backoff

Authentication and permission codes

authentication_required

No bearer credential was sent. Add the Authorization header.

invalid_api_key

The key is malformed or unknown. Check that the entire aig_live_… value was copied.

api_key_expired

The key reached its configured expiry. Create or use a replacement.

api_key_revoked

An admin revoked or rotated this key. Update the integration with an active credential.

insufficient_scope

The credential authenticated but lacks the scope required by this operation.

feature_not_available

The workspace plan or current platform version does not include the requested feature.

admin_required

Only a workspace admin may perform the operation.

Request codes

invalid_request

The request cannot be parsed or does not match the endpoint contract.

unknown_field

A query or body field is not recognised. Correct the spelling rather than removing validation.

invalid_parameter

A parameter has the wrong type, range or format.

invalid_cursor

The pagination cursor is invalid. Reuse next_cursor exactly as returned.

request_too_large

The request body exceeds the endpoint’s hard limit.

Resource and state codes

batch_not_found

No visible translation has that ID. Resources in another workspace intentionally return the same error.

glossary_not_found

No glossary exists for that language pair.

resource_not_found

The requested resource or route does not exist.

glossary_already_exists

A glossary already exists for this language pair. Update it instead of creating another.

result_not_ready

The translation has not completed, so no result can be downloaded yet.

batch_not_editable

The translation’s current state does not allow the requested housekeeping change.

Language and glossary codes

language_not_supported

The tag is outside the supported catalogue. Read GET /v1/languages.

invalid_language_pair

The language-pair identifier cannot be split into two supported BCP 47 tags.

glossary_term_limit_reached

The resulting term count would exceed the workspace plan’s allowance. The update is atomic; nothing changed.

glossary_limit_reached

The workspace has reached its number of glossaries for the current plan.

invalid_glossary_terms

One or more glossary entries are empty, incomplete or otherwise invalid.

Service codes

rate_limited

The credential exceeded a rate window. Wait for Retry-After, then retry with jitter.

internal_error

AI Glot failed unexpectedly. Retry with backoff and retain the request_id.

service_unavailable

A required service is temporarily unavailable. Retry with backoff.