---
title: "Errors"
description: "Handle AI Glot API failures using stable error codes, request IDs, retry guidance and anchored explanations for every documented error."
canonical: "https://ai-glot.com/docs/api/errors"
updated: "2026-08-09"
---

# Errors

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

```json title="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                  |

**Fix before retrying**

Most 400, 401, 403, 404, 409, 413 and 422 responses require a changed credential, identifier, state or request.

**Retry safely**

Retry 429 after `Retry-After`; retry 500 and 503 with exponential backoff and random jitter.

> **Note**
>
> Keep the `request_id` in logs and support messages. It identifies the server-side request without exposing your API key or CSV content.

## 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`](/docs/api/languages/list).

### 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.