> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Reference

> RFC 9457 Problem Details error format used by the Arize REST API — status codes, type URLs, and the error_code field for programmatic error handling.

The Arize REST API uses [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457.html) for all error responses. Every error response has `Content-Type: application/problem+json` and a consistent JSON body.

## Error Response Format

```json theme={null}
{
  "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](#error-codes). |

***

## HTTP Status Codes

<h3 id="invalid-request">
  400 — Invalid Request
</h3>

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

```json theme={null}
{
  "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

***

<h3 id="authentication-required">
  401 — Authentication Required
</h3>

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

```json theme={null}
{
  "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](/ax/rest-reference/overview#authentication).

***

<h3 id="access-forbidden">
  403 — Access Forbidden
</h3>

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.

```json theme={null}
{
  "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.

***

<h3 id="resource-not-found">
  404 — Resource Not Found
</h3>

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.

```json theme={null}
{
  "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."
}
```

<Tip>
  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](/ax/rest-reference/overview#authorization).
</Tip>

***

<h3 id="method-not-allowed">
  405 — Method Not Allowed
</h3>

The HTTP method used is not supported by this endpoint.

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

***

<h3 id="resource-conflict">
  409 — Resource Conflict
</h3>

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

```json theme={null}
{
  "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."
}
```

***

<h3 id="unsupported-media-type">
  415 — Unsupported Media Type
</h3>

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

```json theme={null}
{
  "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"
}
```

***

<h3 id="validation-error">
  422 — Validation Error
</h3>

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

```json theme={null}
{
  "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

***

<h3 id="rate-limit-exceeded">
  429 — Rate Limit Exceeded
</h3>

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

```json theme={null}
{
  "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. |

***

<h3 id="internal-server-error">
  500 — Internal Server Error
</h3>

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

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

***

<h3 id="bad-gateway">
  502 — Bad Gateway
</h3>

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

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

***

<h3 id="service-unavailable">
  503 — Service Unavailable
</h3>

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

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

***

<h2 id="error-codes">
  Error Codes
</h2>

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

```python theme={null}
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)
```