Errors

The error envelope

{
  "error": {
    "message": "Human-readable description of what went wrong",
    "type": "invalid_request_error"
  }
}

This is the same envelope OpenAI's own API uses, so error handling written against an existing OpenAI-compatible client should keep working without changes: check the HTTP status code first, and read error.message for a message worth surfacing to a developer or logging. error.type is a stable, machine-checkable category, useful for branching logic (retry vs. don't retry, prompt for a new API key vs. back off and try again) without parsing the free-text message.

Status codes and types

Status	Type	Meaning
400	invalid_request_error	The request itself is malformed: an unrecognized model, a missing or empty messages array, a message with an unsupported role, or a malformed tools definition. Fix the request; retrying without changing anything will fail the same way every time.
401	authentication_error	The Authorization header is missing, malformed, or the key is invalid, expired, or revoked. See Authentication.
429	rate_limit_error	Too many requests in a short window on this key. See Rate limits for the limit and how to back off correctly.
500	api_error	An unexpected server-side error unrelated to your request. Rare; safe to retry, ideally with a short backoff.
503	api_error	The service is temporarily unable to complete the request, typically a transient issue on tAI's own generation infrastructure rather than anything wrong with your request. Safe to retry.

A few examples

An unknown model:

HTTP/1.1 400 Bad Request

{"error": {"message": "Unknown model: 'tai-4.9'. See https://docs.artfical.com/tai/en for the current list.", "type": "invalid_request_error"}}

An invalid or expired key:

HTTP/1.1 401 Unauthorized

{"error": {"message": "Invalid API key.", "type": "authentication_error"}}

A transient service issue:

HTTP/1.1 503 Service Unavailable

{"error": {"message": "The AI service is temporarily unavailable. Please retry.", "type": "api_error"}}

Errors mid-stream

Once a streaming response has started (the connection is open and chunks have begun arriving), an error can no longer be reported as a normal JSON error body with a non-2xx status, since the HTTP status and headers were already sent as 200 at the start of the stream. Instead, a failure that happens mid-stream is surfaced as a visible content chunk (typically a short bracketed notice) followed by a normal finish chunk and [DONE], rather than the connection simply dropping. See Streaming for the exact shape and why the stream is guaranteed to end cleanly either way.

What's worth retrying

As a general rule: 400 and 401 errors describe something wrong with the request or the key itself, and retrying identically will fail identically every time, so fix the underlying issue first. 429, 500, and 503 are all safe to retry, ideally with a short delay and a cap on total attempts rather than retrying in a tight loop; see Rate limits specifically for how to back off from a 429 correctly.