Reference

Errors

Every status A8 returns for a failed request, with its body, its cause and its fix, and how each SDK raises it.

An error response carries a status, a JSON body in the format of the interface it answers, and an x-request-id header. The body's code names the exact condition and param names the field to change. An abstention is a successful response with status 200. See Accuracy and abstention.

§1Status codes

Status	`type` on the OpenAI interfaces	`type` on Anthropic Messages	Condition
`400`	`invalid_request_error`	`invalid_request_error`	The body asks for something A8 refuses, or holds a value outside its range
`401`	`authentication_error`	`authentication_error`	The key is missing, invalid or revoked
`403`	`permission_error`	`permission_error`	The key lacks the permission the request needs, or its organization lacks access to A8
`404`	`not_found_error`	`not_found_error`	The pinned version names a horizon outside your organization’s stored horizons, the stored response is outside your organization’s store, or the path is outside A8’s routes
`405`	`invalid_request_error`	`invalid_request_error`	The route takes another method
`413`	`invalid_request_error`	`request_too_large`	The body exceeds the size limit
`429`	`rate_limit_error`	`rate_limit_error`	The organization is over its rate limit
`500`	`server_error`	`api_error`	An error on our side
`503`	`server_error`	`overloaded_error`	A version, a dependency or key verification is briefly unavailable

Table 1. Status codes. The SDKs retry 429, 500 and 503 on their own (Table 4).

An abstention and a filtered request both return 200, in the slots each API keeps for them. Each interface’s page shows them.

§2Error bodies

The OpenAI interfaces return OpenAI's error object. Anthropic Messages returns Anthropic's envelope, with the same code and param inside it:

JSON

{
  "error": {
    "message": "Set the minimum accuracy with the model's tag, as a8:95.",
    "type": "invalid_request_error",
    "param": "min_accuracy",
    "code": "unsupported_parameter",
    "request_id": "req_5b456a869547474cc316c4fc48017e19"
  }
}

JSON

{
  "error": {
    "message": "Set the minimum accuracy with the model's tag, as a8:95.",
    "type": "invalid_request_error",
    "param": "min_accuracy",
    "code": "unsupported_parameter",
    "request_id": "req_5b456a869547474cc316c4fc48017e19"
  }
}

JSON

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Set the minimum accuracy with the model's tag, as a8:95.",
    "param": "min_accuracy",
    "code": "unsupported_parameter"
  },
  "request_id": "req_5b456a869547474cc316c4fc48017e19"
}

JSON

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "model: Tag the model with a level from 0 to 99, as a8:95."
    }
  ]
}

Recorded from a8-1-1@20260715t140322z on 2026-10-22.

Over MCP, a failed call is a tool result with isError set, and its text names the field and the value that passes. See MCP.

The bodies below are the Chat Completions form. On the other interfaces the message names that interface’s own fields.

§3`400` Bad request

§3.1`unsupported_parameter`

The body carries a field A8 refuses: min_accuracy or expected on Chat Completions, Responses or Anthropic Messages, or conversation on Responses.

JSON

{
  "error": {
    "message": "Teach through MCP. A request carries the conversation.",
    "type": "invalid_request_error",
    "param": "expected",
    "code": "unsupported_parameter",
    "request_id": "req_0c9e3f1a2b4d5e6f7a8b9c0d1e2f3a4b"
  }
}

Fix: set the minimum accuracy with the model’s tag, as a8:95, and teach through MCP. On Responses, continue a conversation with previous_response_id.

§3.2`unsupported_value`

A field holds a value outside the set A8 accepts, or the request lacks a part it needs. param names the field:

Minimum accuracy: a model tag other than a whole number from 0 to 99 (param is model).
Reasoning: an effort value the interface lacks, or a thinking.type other than adaptive, enabled or disabled.
Choices: an n outside 1 to 128.
Verdict shape: the json_object response format, a schema other than a JSON Schema object, a score property whose minimum is at or above its maximum, or a tool_choice naming a tool outside tools.
Request parts: a request that leaves out its criterion (param is criterion), a message that leaves out its role, or a subject standard other than a string or a list of strings.
Responses fields: a store other than a boolean, a previous_response_id or instructions other than a string, and an order, limit or after outside its range on input_items.

JSON

{
  "error": {
    "message": "Tag the model with a level from 0 to 99, as a8:95.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "unsupported_value",
    "request_id": "req_7d1b2c3e4f5a6b7c8d9e0f1a2b3c4d5e"
  }
}

Fix: send a value from the range the message names. For a missing criterion, the message reads Send a criterion: what the subject is judged against. and names where the criterion travels in the interface. The minimum accuracy’s tag is on Accuracy and abstention, and each interface’s effort values are on its own page. For a structured verdict, use json_schema, which names the fields to answer in.

§3.3`missing_subject`

The request holds a criterion and leaves the subject empty: the conversation holds system messages alone, ends with an assistant message or ends with an empty user message. In Responses, input is empty or absent.

JSON

{
  "error": {
    "message": "End the conversation with the user message to judge.",
    "type": "invalid_request_error",
    "param": "messages",
    "code": "missing_subject",
    "request_id": "req_2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d"
  }
}

Fix: end the conversation with a user message that holds the subject or the follow-up.

§3.4`unsupported_content`

A subject part holds an image, audio or a file. A8 reads text.

JSON

{
  "error": {
    "message": "Send the subject as text: a string, or a list of text parts.",
    "type": "invalid_request_error",
    "param": "messages[1].content[0]",
    "code": "unsupported_content",
    "request_id": "req_3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e"
  }
}

Fix: send the subject as a string, or a list of text parts.

§3.5`unknown_subject_key`

The subject is a JSON object with output and a key outside output, reference, context and question. param names the key under subject.

JSON

{
  "error": {
    "message": "A subject takes output, reference, context and question.",
    "type": "invalid_request_error",
    "param": "subject.answer",
    "code": "unknown_subject_key",
    "request_id": "req_4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f"
  }
}

Fix: rename the key to one of the four. See API overview.

§3.6`invalid_json`

The body is something other than a JSON object.

JSON

{
  "error": {
    "message": "Send the body as a JSON object.",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_json",
    "request_id": "req_4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a"
  }
}

Fix: send the body as a JSON object.

§3.7`unknown_model`

model is outside A8’s identifiers, or names a version we have yet to publish.

JSON

{
  "error": {
    "message": "Use a8, or an identifier from GET /models.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "unknown_model",
    "request_id": "req_5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a"
  }
}

Fix: send a8, or an identifier the models list names.

§3.8`previous_response_not_found`

On Responses, previous_response_id names a response outside your organization’s store: an unknown ID, a response stored more than 30 days ago, a deleted response or one sent with store: false.

JSON

{
  "error": {
    "message": "Previous response eval-3b7e0a12c4d5f6a8 was not found.",
    "type": "invalid_request_error",
    "param": "previous_response_id",
    "code": "previous_response_not_found",
    "request_id": "req_6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b"
  }
}

Fix: send the id of a stored response, or send the earlier items of the conversation in input.

§3.9`context_length_exceeded`

The request holds more tokens than A8 reads in one request (Table 3).

JSON

{
  "error": {
    "message": "The request holds more tokens than A8 reads in one request.",
    "type": "invalid_request_error",
    "param": null,
    "code": "context_length_exceeded",
    "request_id": "req_6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b"
  }
}

Fix: shorten the subject or the criterion.

§4`401` Unauthorized

§4.1`invalid_api_key`

The key is missing, invalid or revoked. The message names the cause: a missing key gets the message below, and an invalid or revoked key gets The API key is invalid or revoked.

JSON

{
  "error": {
    "message": "Send a valid API key as Authorization: Bearer <key>.",
    "type": "authentication_error",
    "param": null,
    "code": "invalid_api_key",
    "request_id": "req_6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b"
  }
}

Fix: send a current key. A revoked key returns 401 within about a minute of revocation. See API keys.

§5`403` Forbidden

§5.1`missing_permission`

The key is valid and lacks the permission the request needs. The message names it.

JSON

{
  "error": {
    "message": "This request needs the models:explain permission.",
    "type": "permission_error",
    "param": null,
    "code": "missing_permission",
    "request_id": "req_7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c"
  }
}

Fix: use a key that holds the permission, or grant it to a new key. See API keys.

§5.2`model_not_enabled`

The key is valid and its organization lacks access to A8. Every request from it returns this, over MCP as well, until we turn A8 on for the organization.

JSON

{
  "error": {
    "message": "A8 is off for this organization; request it in the console.",
    "type": "permission_error",
    "param": null,
    "code": "model_not_enabled",
    "request_id": "req_1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a"
  }
}

Fix: request access in Console → A8. We write to you when A8 is on for your organization.

§6`404` Unknown horizon, response or route

§6.1`horizon_not_found`

A pinned identifier names a horizon outside your organization’s stored horizons: a typo, or a provisional horizon that a later teach replaced.

JSON

{
  "error": {
    "message": "a8-1-1@20260716t090000z names an unknown horizon.",
    "type": "not_found_error",
    "param": "model",
    "code": "horizon_not_found",
    "request_id": "req_8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d"
  }
}

Fix: pin an identifier from GET /models. See Horizons and Deprecations.

§6.2`response_not_found`

On Responses, GET /responses/{id}, GET /responses/{id}/input_items or DELETE /responses/{id} names a response outside your organization’s store: an unknown ID, a response stored more than 30 days ago, a deleted response or one sent with store: false.

JSON

{
  "error": {
    "message": "Response eval-3b7e0a12c4d5f6a8 was not found.",
    "type": "not_found_error",
    "param": "response_id",
    "code": "response_not_found",
    "request_id": "req_9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e"
  }
}

Fix: send the id of a response stored within the last 30 days.

§6.3`route_not_found`

The path is outside A8’s routes. The body is in the format of the interface the path starts with, and the OpenAI format elsewhere.

JSON

{
  "error": {
    "message": "POST /eval/v1/verdicts is outside A8's routes.",
    "type": "not_found_error",
    "param": null,
    "code": "route_not_found",
    "request_id": "req_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b"
  }
}

Fix: send the request to a route on API overview.

§7`405` Wrong method

§7.1`method_not_allowed`

The path names a route that takes another method. The allow header names it, and so does the message.

JSON

{
  "error": {
    "message": "/eval/v1/chat/completions takes POST.",
    "type": "invalid_request_error",
    "param": null,
    "code": "method_not_allowed",
    "request_id": "req_6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c"
  }
}

Fix: send the request with the method the allow header names.

§8`413` Request too large

§8.1`request_too_large`

The body exceeds the size limit in Table 3.

Fix: send a smaller body. Split a long subject into requests of their own.

§9`429` Too many requests

§9.1`rate_limit_exceeded`

The organization is over its requests or tokens per minute. The response carries retry-after and the x-ratelimit-* headers.

JSON

{
  "error": {
    "message": "Rate limit reached for requests per minute. Retry after 2s.",
    "type": "rate_limit_error",
    "param": null,
    "code": "rate_limit_exceeded",
    "request_id": "req_9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e"
  }
}

Fix: wait for retry-after. The SDKs do this on their own. See Rate limits.

§10`500` Internal server error

§10.1`internal_error`

An error on our side. The request ID lets us find it.

Fix: retry. When it repeats, write to [email protected] with the x-request-id.

§11`503` Service unavailable

Each 503 carries a code for its cause, and two of them a retry-after:

`code`	Cause	`retry-after`
`horizon_fitting`	The pinned version is the provisional horizon, still being fitted	`30`
`upstream_unavailable`	A dependency is briefly unavailable	`5`
`key_verification_unavailable`	Key verification is briefly unavailable	Absent: use your own backoff

Table 2. The causes of a 503. A request pinned to a provisional horizon waits for its model this way.

JSON

{
  "error": {
    "message": "a8-1-1@20260722t101500z is being fitted. Retry after 30s.",
    "type": "server_error",
    "param": "model",
    "code": "horizon_fitting",
    "request_id": "req_0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f"
  }
}

Fix: retry after the interval. The SDKs do this on their own.

§12Request limits

Limit	Value
Request body	TBD (size in MiB)
Tokens in one request	TBD (input tokens)
Properties in a verdict shape	TBD (count)
Text parts in a subject	TBD (count)

Table 3. Request limits. A body over its size returns 413; a request over its tokens returns 400 with the code context_length_exceeded.

§13Errors in the SDKs

The OpenAI and Anthropic SDKs raise one exception class per status:

Status	OpenAI SDK	Anthropic SDK
`400`	`BadRequestError`	`BadRequestError`
`401`	`AuthenticationError`	`AuthenticationError`
`403`	`PermissionDeniedError`	`PermissionDeniedError`
`404`	`NotFoundError`	`NotFoundError`
`405`, `413`	`APIStatusError`	`APIStatusError`
`429`	`RateLimitError`	`RateLimitError`
`500`, `503`	`InternalServerError`	`InternalServerError`
Connection failure	`APIConnectionError`	`APIConnectionError`

Table 4. The exception each status raises. Both SDKs retry 408, 409, 429 and every status from 500 up twice by default, with backoff that honours retry-after.

Branch on the body's code:

Python

import openai

try:
    resp = client.chat.completions.create(**request)
except openai.PermissionDeniedError as error:
    print(error.code)        # "missing_permission"
    print(error.request_id)  # quote it in a support request
except openai.BadRequestError as error:
    print(error.code, error.param)  # the condition, and the field to change

TypeScript

import OpenAI from "openai";

try {
  const resp = await client.chat.completions.create(request);
} catch (error) {
  if (error instanceof OpenAI.PermissionDeniedError) {
    console.log(error.code); // "missing_permission"
    console.log(error.requestID); // quote it in a support request
  } else if (error instanceof OpenAI.BadRequestError) {
    console.log(error.code, error.param); // the condition, and the field
  } else {
    throw error;
  }
}

§14Request IDs

Every response, an error included, carries an x-request-id header, and the error body carries the same ID as request_id. Quote it in a support request. See API overview for where each SDK exposes it.

Next steps

API overviewWhat every request to A8 shares, from the base URL and authentication to the request parts and the response fields.Rate limitsHow A8 limits requests and tokens per organization, the headers that report the limits, and how to raise them.API keysCreate an API key, grant its permissions, authenticate requests with it and revoke it.

§1Status codes

§2Error bodies

§3400 Bad request

§3.1unsupported_parameter

§3.2unsupported_value

§3.3missing_subject

§3.4unsupported_content

§3.5unknown_subject_key

§3.6invalid_json

§3.7unknown_model

§3.8previous_response_not_found

§3.9context_length_exceeded

§4401 Unauthorized

§4.1invalid_api_key

§5403 Forbidden

§5.1missing_permission

§5.2model_not_enabled

§6404 Unknown horizon, response or route

§6.1horizon_not_found

§6.2response_not_found

§6.3route_not_found

§7405 Wrong method

§7.1method_not_allowed

§8413 Request too large

§8.1request_too_large

§9429 Too many requests

§9.1rate_limit_exceeded

§10500 Internal server error

§10.1internal_error

§11503 Service unavailable

§12Request limits

§13Errors in the SDKs

§14Request IDs

Next steps

§3`400` Bad request

§3.1`unsupported_parameter`

§3.2`unsupported_value`

§3.3`missing_subject`

§3.4`unsupported_content`

§3.5`unknown_subject_key`

§3.6`invalid_json`

§3.7`unknown_model`

§3.8`previous_response_not_found`

§3.9`context_length_exceeded`

§4`401` Unauthorized

§4.1`invalid_api_key`

§5`403` Forbidden

§5.1`missing_permission`

§5.2`model_not_enabled`

§6`404` Unknown horizon, response or route

§6.1`horizon_not_found`

§6.2`response_not_found`

§6.3`route_not_found`

§7`405` Wrong method

§7.1`method_not_allowed`

§8`413` Request too large

§8.1`request_too_large`

§9`429` Too many requests

§9.1`rate_limit_exceeded`

§10`500` Internal server error

§10.1`internal_error`

§11`503` Service unavailable