Error Reference - Arize AX Docs

The Arize REST API uses RFC 9457 Problem Details for all error responses. Every error response has Content-Type: application/problem+json and a consistent JSON body.

Error Response Format

{
  "status": 400,
  "title": "Bad Request",
  "type": "https://arize.com/docs/ax/rest-reference/errors#invalid-request",
  "detail": "JSON parse error: unexpected token '}' at position 42."
}

Fields

Field	Type	Required	Description
`status`	integer	Yes	The HTTP status code.
`title`	string	Yes	A short, stable, human-readable summary of the problem type. This string does not change between occurrences of the same error class.
`type`	string (URI)	No	A URI that identifies the problem type and links to this documentation page. Clients can use this to route errors programmatically.
`detail`	string	No	A human-readable explanation specific to this occurrence of the problem. Describes what went wrong and, where possible, how to fix it.
`instance`	string (URI)	No	A URI identifying the specific resource involved in the error.
`error_code`	string (enum)	No	A stable, machine-readable code identifying the error subtype within an HTTP status class. Use this to branch on specific error causes without parsing `detail` strings. See Error Codes.

HTTP Status Codes

400 — Invalid Request

The request was malformed and could not be parsed — for example, the body is not valid JSON or a field has the wrong type.

{
  "status": 400,
  "title": "Bad Request",
  "type": "https://arize.com/docs/ax/rest-reference/errors#invalid-request",
  "detail": "JSON parse error: unexpected token '}' at position 42."
}

Common causes:

Malformed or unparseable JSON body
Field value of the wrong type (e.g., string where integer expected)
Invalid resource ID format

401 — Authentication Required

The request did not include valid credentials, or the provided credentials are invalid or expired.

{
  "status": 401,
  "title": "Unauthorized",
  "type": "https://arize.com/docs/ax/rest-reference/errors#authentication-required",
  "detail": "Bearer credentials are required (API key or OAuth access token)."
}

Common causes:

Missing Authorization header
Expired or revoked API key
Expired OAuth access token — re-authenticate and retry
Unrecognized credential format

Fix: Ensure you are sending a valid API key or access token in the Authorization: Bearer <credential> header. See Authentication.

403 — Access Forbidden

The caller is authenticated but lacks permission for the requested action on a resource they can read. This is distinct from 404: a 403 confirms the resource exists but the action is not allowed.

{
  "status": 403,
  "title": "Forbidden",
  "type": "https://arize.com/docs/ax/rest-reference/errors#access-forbidden",
  "detail": "You do not have permission to delete this dataset."
}

Fix: Check that your API key has the required role/permission for the action. Contact your space admin if you need elevated access.

404 — Resource Not Found

The requested resource does not exist, or the caller has no read access to it. The API intentionally does not distinguish between these two cases to prevent resource enumeration.

{
  "status": 404,
  "title": "Not Found",
  "type": "https://arize.com/docs/ax/rest-reference/errors#resource-not-found",
  "detail": "Dataset with ID 'ZGF0YXNldC10ZXN0' was not found."
}

If you receive a 404 and believe the resource exists, verify that your API key has read access to the space or project containing the resource. See Authorization.

405 — Method Not Allowed

The HTTP method used is not supported by this endpoint.

{
  "status": 405,
  "title": "Method Not Allowed",
  "type": "https://arize.com/docs/ax/rest-reference/errors#method-not-allowed",
  "detail": "method not allowed"
}

409 — Resource Conflict

The request conflicts with the current state of the server, typically because a resource with the same unique identifier already exists.

{
  "status": 409,
  "title": "Conflict",
  "type": "https://arize.com/docs/ax/rest-reference/errors#resource-conflict",
  "detail": "A dataset named 'my-dataset' already exists in this space."
}

415 — Unsupported Media Type

The Content-Type header is missing or not supported. Endpoints that accept a request body require Content-Type: application/json.

{
  "status": 415,
  "title": "Unsupported Media Type",
  "type": "https://arize.com/docs/ax/rest-reference/errors#unsupported-media-type",
  "detail": "Content-Type must be application/json"
}

422 — Validation Error

The request was well-formed but failed semantic validation — for example, a required field is missing or a value is outside the allowed range.

{
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "https://arize.com/docs/ax/rest-reference/errors#validation-error",
  "detail": "The 'name' field is required and must be a non-empty string."
}

Common causes:

Missing required fields
Value outside the allowed range or not in the allowed enum set

429 — Rate Limit Exceeded

The caller has exceeded the allowed request rate. The response includes a Retry-After header indicating how many seconds to wait before retrying.

{
  "status": 429,
  "title": "Too Many Requests",
  "type": "https://arize.com/docs/ax/rest-reference/errors#rate-limit-exceeded",
  "detail": "You have exceeded the allowed number of requests. Please try again later."
}

Response headers:

Header	Description
`Retry-After`	Number of seconds to wait before retrying.

500 — Internal Server Error

An unexpected error occurred on the server. This is not caused by the client request and is safe to retry with exponential backoff.

{
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://arize.com/docs/ax/rest-reference/errors#internal-server-error",
  "detail": "An unexpected error occurred."
}

502 — Bad Gateway

The server received an invalid response from an upstream service. Retry with exponential backoff.

{
  "status": 502,
  "title": "Bad Gateway",
  "type": "https://arize.com/docs/ax/rest-reference/errors#bad-gateway"
}

503 — Service Unavailable

The service is temporarily unavailable, usually due to maintenance or overload. Retry with exponential backoff.

{
  "status": 503,
  "title": "Service Unavailable",
  "type": "https://arize.com/docs/ax/rest-reference/errors#service-unavailable"
}

Error Codes

The error_code field provides a stable, machine-readable identifier for the specific error subtype. It is only present on 4xx responses where the distinction is actionable by the client. Server errors (5xx) do not include error_code.

`error_code`	HTTP Status	Description
`VALIDATION_ERROR`	400	The request body failed schema validation (e.g. malformed JSON, wrong field type).
`MISSING_REQUIRED_FIELD`	422	A required field is absent or empty. The `detail` field names the missing field.
`INVALID_FIELD_VALUE`	422	A field is present but its value is invalid (out of range, wrong format, etc.).
`INVALID_ENUM_VALUE`	422	A field contains a value not in the allowed enum set.
`INVALID_ID`	400	A resource ID could not be decoded (wrong format or wrong type).
`RESOURCE_NOT_FOUND`	404	The requested resource does not exist or is not accessible to the caller.
`RESOURCE_ALREADY_EXISTS`	409	A resource with the same unique identifier already exists.
`ACCESS_DENIED`	403	The caller is authenticated but lacks permission for this action on this resource.
`AUTHENTICATION_REQUIRED`	401	No credentials were provided, or the credential format was not recognized.
`INVALID_CREDENTIALS`	401	Credentials were provided but are invalid, expired, or revoked.
`RATE_LIMIT_EXCEEDED`	429	The caller has exceeded the allowed request rate. Check the `Retry-After` header.
`UNSUPPORTED_MEDIA_TYPE`	415	The `Content-Type` header is missing or not `application/json`.
`METHOD_NOT_ALLOWED`	405	The HTTP method is not supported by this endpoint.

Using error_code in client code

import httpx

response = httpx.post(
    "https://api.arize.com/v2/datasets",
    headers={"Authorization": f"Bearer {api_key}"},
    json=payload,
)

if not response.is_success:
    error = response.json()
    status = error["status"]
    error_code = error.get("error_code")
    detail = error.get("detail", error["title"])

    if status == 401:
        if error_code == "INVALID_CREDENTIALS":
            raise ExpiredCredentialsError("Session expired — re-authenticate and retry")
        raise AuthenticationError(detail)
    elif status == 400:
        if error_code == "INVALID_ID":
            raise ValueError(f"Invalid ID format: {detail}")
        raise BadRequestError(detail)
    elif status == 422:
        if error_code == "MISSING_REQUIRED_FIELD":
            raise ValueError(f"Missing field: {detail}")
        raise ValidationError(detail)
    elif status == 404:
        raise NotFoundError(detail)
    elif status == 429:
        retry_after = int(response.headers.get("Retry-After", 60))
        raise RateLimitError(detail, retry_after=retry_after)
    elif status >= 500:
        raise ServerError(detail)
    else:
        raise ApiError(status, detail)

REST API

Reference

Documentation Index

​Error Response Format

​Fields

​HTTP Status Codes

​400 — Invalid Request

​401 — Authentication Required

​403 — Access Forbidden

​404 — Resource Not Found

​405 — Method Not Allowed

​409 — Resource Conflict

​415 — Unsupported Media Type

​422 — Validation Error

​429 — Rate Limit Exceeded

​500 — Internal Server Error

​502 — Bad Gateway

​503 — Service Unavailable

​Error Codes

​Using error_code in client code

Error Response Format

Fields

HTTP Status Codes

400 — Invalid Request

401 — Authentication Required

403 — Access Forbidden

404 — Resource Not Found

405 — Method Not Allowed

409 — Resource Conflict

415 — Unsupported Media Type

422 — Validation Error

429 — Rate Limit Exceeded

500 — Internal Server Error

502 — Bad Gateway

503 — Service Unavailable

Error Codes

Using error_code in client code