⚠️ Error Codes

Every Bluente API response — success or error — is returned with HTTP status 200. Don’t rely on the HTTP status; read the code field in the JSON body instead.

📦 Response Format

{
  "code": 0,
  "message": "success",
  "data": { }
}

Field	Type	Description
`code`	int	`0` means success. Any other value is an error (see the table below)
`message`	string	`"success"`, or a human-readable description of the error
`data`	any	The result. Only read it when `code` is `0`, unless an endpoint documents error details in `data` (see Validate Options)

The Download File API returns the file as a binary stream on success, and this JSON format on error.

📋 Error Codes

Code	Meaning	Typical causes	What to do
`0`	Success	—	—
`20`	Invalid API key	Missing `Authorization` header, a key that doesn’t start with `sk-`, or an expired or revoked key	Check the header and the key. See API Key
`40`	Invalid parameters	Invalid request body, missing file, unknown language code, unsupported option for this file (for example an IDML-incompatible option), conflicting features, invalid `page_range` (see the `500` row)	Fix the request. Don’t retry it unchanged
`41`	No permission	The task was uploaded by a different user, or the selected feature is not enabled for the account	Use the API key of the user who uploaded the file, or remove the feature
`43`	Not found	The task `id` doesn’t exist (returned by Validate Options)	Check the task `id`
`70`	Insufficient or expired credits	The account doesn’t have enough unexpired credits for the document	Check Get Account and top up
`80`	Already submitted	`POST /translate` was called again for a task that has already been started and charged	Don’t resend. Poll Get Translation Status
`500`	Server error	An unexpected error. Some lookups also currently return `500`, for example an unknown task `id` on `/translate` or `/check` (`message`: `"record not found"`), a download that isn’t available, or an invalid `page_range` for some file types	Check the `message`. Retry later if it persists

Codes not listed here are reserved and not returned by the public translation API today. Treat any non-zero code as an error.

💡 Examples

{
  "code": 20,
  "message": "Unauthorized"
}

{
  "code": 40,
  "message": "IDML translation supports the complete document, not page selections"
}

{
  "code": 70,
  "message": "credits expired"
}

⏳ Upload Errors Are Reported Later

Upload File is asynchronous. It returns a task id as soon as the file is received — before the file is processed and its pages are counted. A successful upload response therefore does not mean the file is usable.

Problems with the file itself — for example an unsupported or corrupt file, or a password-protected document — are reported later by Get Translation Status:

status becomes ERROR, and message describes the problem.
Poll /check until the status is SERVICE_PROCESSED before you call Translate File.

Errors that happen while the document is being translated are also reported by /check (status ERROR) and by the Webhook, if one is configured.

📌 Notes

Always check code before reading data.
Codes 40, 41 and 43 mean the request itself needs to change. Retrying it unchanged returns the same error.

Webhook Overview