Errors

LLMAPI returns HTTP status codes and structured error information where possible. Different protocols keep their corresponding error shapes, so there is not only one JSON error format.

Common Error Shapes

Anthropic/OpenAI compatible endpoints often return:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Request body is empty"
  }
}

OpenAI image endpoints often return:

{
  "error": {
    "type": "not_found_error",
    "message": "Images API is not supported for this platform"
  }
}

Task API business errors commonly use the following shape. Authentication failures still use authentication_error:

{
  "error": {
    "type": "TASK_INVALID_REQUEST",
    "message": "params is required"
  }
}

Common HTTP Status Codes

Status	Meaning	Common causes
400	Invalid request	Invalid JSON, wrong parameter type, or platform group mismatch.
401	Authentication failed	Missing or invalid API key.
403	Permission denied	Insufficient balance, wrong key type, image generation disabled, or content moderation blocked.
404	Endpoint or capability unavailable	Non-OpenAI group calling OpenAI synchronous image endpoints, or OpenAI group calling token count.
409	State conflict	Canceling a task that already finished.
413	Request body too large	Request exceeds the configured body limit.
429	Rate limited	Too many concurrent requests or queued tasks.
500	Server error	Unexpected server error.
502	Provider error	The model provider returned an error.
503	Service unavailable	Tasks disabled, storage not configured, or no available accounts.
504	Timeout	The request or task timed out.

Task API Errors

Reason	HTTP status	Meaning
authentication_error	401	API key is missing or invalid.
TASKS_DISABLED	503	Task API service is disabled.
TASKS_PAUSED	503	Task API processing is temporarily paused.
TASK_SCOPE_REQUIRED	403	The API key is not enabled for Task APIs.
TASK_INVALID_REQUEST	400	Request body is invalid.
TASK_UNSUPPORTED_MODEL	400	Requested model is not available for Task API.
TASK_UNSUPPORTED_ADAPTER	400	Requested model does not support this task type.
TASK_NO_CAPABLE_ROUTE	400	No available channel can preserve the requested parameters or input-asset combination.
TASK_PRICING_UNAVAILABLE	503	Pricing is unavailable for the requested model or parameters.
TASK_STORAGE_UNAVAILABLE	503	Result asset storage is unavailable.
TASK_INSUFFICIENT_BALANCE	403	Balance is insufficient for the estimated task cost.
TASK_QUEUE_LIMIT_EXCEEDED	429	User or API key queue limit was reached.
TASK_ALREADY_TERMINAL	409	Task is already finished and cannot be canceled.
TASK_NOT_FOUND	404	Task does not exist or is not accessible with this API key.

Platform Restriction Errors

Non-OpenAI group calling an OpenAI synchronous image endpoint:

{
  "error": {
    "type": "not_found_error",
    "message": "Images API is not supported for this platform"
  }
}

OpenAI group calling token count:

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "Token counting is not supported for this platform"
  }
}

Retry Guidance

Error type	Recommendation
400, 401, 403, 404	Do not retry unchanged; fix request, authentication, group, or permission first.
409	Fetch the latest task state before deciding what to do next.
413	Reduce request body or uploaded resource size.
429	Retry with exponential backoff and reduce concurrency or queued tasks.
500, 502, 503, 504	Retry with exponential backoff; for accepted Task API, query task status first to avoid duplicate submissions.

If POST /v1/tasks returned 202, use the returned id for follow-up checks instead of immediately submitting a duplicate task after a client-side timeout.