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.
{
"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 JSON body property is not recognised. Correct the spelling rather than removing validation. Unrecognised query parameters never produce this error; they are ignored, so a mistyped filter returns an unfiltered 200.
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.
File and format codes
unsupported_format
The file extension is not one AI Glot accepts. See Files and formats for the twelve families and their extensions.
file_too_large
The file exceeds the ceiling for its format. Limits are per format rather than global (60 MB for CSV, 4 MB for a PO catalogue), so a size that works for one extension can be refused for another.
file_fetch_failed
file_url could not be retrieved. The URL must be HTTPS and must be the final destination: redirects are not followed, so a shortened or signed-then-redirected link fails here.
file_retention_expired
The uploaded file has passed its retention window and is no longer stored. Create the translation again from the source file.
file_expired
The file backing this translation is gone, so the operation cannot proceed.
result_too_large
The finished translation exceeds the size that can be returned. Split the source file and translate it in parts.
Plan and approval codes
plan_invalid
The instruction or refinement could not be turned into a usable plan. Rephrase it: naming the fields or columns to translate is more reliable than describing them.
no_plan_yet
Approval was attempted before a plan existed. Call POST /v1/batches/{batch_id}/plan first; this guard is what stops an integration charging a workspace for a translation nobody described.
batch_not_awaiting_approval
The translation is not in a state where approval applies; it is usually already running or already finished. Poll GET /v1/batches/{batch_id} instead of approving again.
insufficient_credits
The workspace balance cannot cover the plan’s measured cost. Nothing is reserved, so the translation stays approvable once credits are added.
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.