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

# Error codes

> How the API reports errors, the status codes you will see, and how to handle them.

When a request fails, the API returns the matching HTTP status code and a JSON body describing what went wrong. Every response also carries an `x-request-id` header, which error bodies repeat as `requestId`. Include it when you contact support. The [TypeScript SDK](/sdk/pay-errors) turns each response into a typed error for you, so most integrations never parse this body by hand.

## Error response format

```json theme={"system"}
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": ["amount must be a positive number"],
  "errors": [{ "field": "amount", "message": "must be a positive number" }],
  "timestamp": "2026-08-06T12:00:00.000Z",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}
```

| Field | Type | Description |
| - | - | - |
| `statusCode` | number | The HTTP status code, repeated in the body. |
| `error` | string | Short error category, such as `Bad Request` or `Not Found`. |
| `message` | string or string\[] | Human-readable detail. Validation failures return an array, one entry per problem. |
| `errors` | array | On `400` validation errors: one `{ field, message }` per invalid field. |
| `timestamp` | string | ISO 8601 time the error was produced. |
| `requestId` | string | Correlates the request. Also returned as the `x-request-id` response header. |
| `code` | string | On some errors only: a stable, machine-readable code such as `key_no_longer_valid`. Branch on it when it is present. |

## Status codes

| Status | Meaning | When it occurs |
| - | - | - |
| `400` | Bad request | Missing or invalid parameters. See the `errors` array. |
| `401` | Unauthorized | Missing or invalid API key, or a key whose creator no longer administers the business (`key_no_longer_valid`). |
| `403` | Forbidden | Valid key, but no access to this resource. |
| `404` | Not found | The resource does not exist, or is not in your organization or environment. |
| `409` | Conflict | The request conflicts with the record's current state: another request changed it, a product reached its purchase limit, or a state code such as `client_joined` applies. For a concurrent change, read the record again, then retry the write. A repeated idempotency key never returns `409`. |
| `429` | Rate limited | Too many requests from your IP address to one endpoint. Honor the `Retry-After` header. See [Rate limits](/api-reference/introduction#rate-limits). |
| `5xx` | Server error | Something went wrong on our side. Safe to retry with backoff. |

## Common scenarios

### Validation (400)

`message` lists each problem, and `errors` names the offending `field`.

```json theme={"system"}
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": ["currency must be EUR or USD"],
  "errors": [{ "field": "currency", "message": "must be EUR or USD" }],
  "timestamp": "2026-08-06T12:00:00.000Z",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}
```

### Authentication (401)

The `x-api-key` header is missing or the key is wrong. Check you are using the right key: `sk_test_` for test mode, `sk_live_` for live mode.

### Not found (404)

The resource ID is wrong, or it belongs to a different environment. Test and live data are separate.

### Rate limited (429)

Back off and retry. The `Retry-After` header tells you how many seconds to wait.

## Handling errors with the SDK

The [TypeScript SDK](/sdk/pay-errors) maps every error response to a typed `AgentaOSError` subclass with `status`, `code`, `message`, `requestId`, and (on validation) `errors`. A `409` becomes `IdempotencyError`, whatever its cause. The SDK retries a `429`, a `5xx` and a network error for you.

```typescript theme={"system"}
import { AgentaOSError, ValidationError } from '@agentaos/pay';

try {
  await agentaos.checkouts.create({ amount: -1 });
} catch (err) {
  if (err instanceof ValidationError) {
    console.error(err.errors); // [{ field: 'amount', message: '...' }]
  } else if (err instanceof AgentaOSError) {
    console.error(err.status, err.code, err.requestId);
  }
}
```

## Environments

There is one base URL. Your key prefix selects the environment: `sk_test_` uses test mode, `sk_live_` uses live mode. See [Test mode](/getting-started/test-mode).

## Support

Include the `requestId` (or the `x-request-id` header) from the failed response when you contact support. It lets us find the exact request.


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