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

# Errors

> Understand API errors and status codes.

Errors use standard HTTP status codes and a consistent JSON response format.

## Error format

Errors are returned in the following format:

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "The request contains invalid data.",
    "request_id": "req_..."
  }
}
```

| Field | Description |
| - | - |
| `code` | Machine-readable error code |
| `message` | Human-readable description |
| `request_id` | Unique identifier for the request |

> [!NOTE]
>
> Include the `request_id` when contacting Key2Arena support about a failed API request.

## HTTP status codes

| Status | Meaning |
| - | - |
| `400` | The request could not be processed |
| `401` | Authentication is missing, invalid, or expired |
| `403` | The authenticated client does not have permission |
| `404` | The requested resource was not found |
| `405` | The HTTP method is not supported by the endpoint |
| `409` | The request conflicts with the current state |
| `422` | The request contains invalid data |
| `429` | Too many requests |
| `500` | An unexpected server error occurred |

## Authentication errors

### Unauthorized

Returned when the access token is missing, invalid, revoked, or expired.

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Authentication credentials are missing, invalid, or expired.",
    "request_id": "req_..."
  }
}
```

### Insufficient scope

Returned when the access token does not include the scope required by the endpoint.

```json theme={null}
{
  "error": {
    "code": "insufficient_scope",
    "message": "The access token does not have permission to perform this action.",
    "required_scopes": [
      "orders:create"
    ],
    "request_id": "req_..."
  }
}
```

## Validation errors

Invalid request data returns `422 Unprocessable Entity`.

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "The request contains invalid data.",
    "errors": {
      "items": [
        "The items field is required."
      ]
    },
    "request_id": "req_..."
  }
}
```

The `errors` object contains validation messages for each invalid field.

## Order errors

### Insufficient balance

Returned when the account does not have enough available balance to complete the order.

```json theme={null}
{
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient available balance.",
    "request_id": "req_..."
  }
}
```

The order is not created and the account is not charged.

### Idempotency conflict

Returned when an `Idempotency-Key` is reused with different order data.

```json theme={null}
{
  "error": {
    "code": "idempotency_conflict",
    "message": "This Idempotency-Key has already been used for a different request.",
    "request_id": "req_..."
  }
}
```

Use a new `Idempotency-Key` when creating a different order.

## Not found

Returned when a requested product, order, or other resource cannot be found.

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "request_id": "req_..."
  }
}
```

## Rate limits

When the request limit is exceeded, the API returns `429 Too Many Requests`.

```json theme={null}
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please try again later.",
    "retry_after": 30,
    "request_id": "req_..."
  }
}
```

When provided, `retry_after` indicates how long to wait before retrying the request.

## Server errors

Unexpected errors return `500 Internal Server Error`.

```json theme={null}
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred while processing the request.",
    "request_id": "req_..."
  }
}
```

> [!WARNING]
>
> For `500` responses, avoid immediately creating a new order with a different `Idempotency-Key`. Retry the original request with the same key to prevent duplicate purchases.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.