Error codes

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 turns each response into a typed error for you, so most integrations never parse this body by hand.

Error response format

{
  "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.
`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.

{
  "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 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.

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.

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.

SDK

CLI

API Reference

Error response format

Status codes

Common scenarios

Validation (400)

Authentication (401)

Not found (404)

Rate limited (429)

Handling errors with the SDK

Environments

Support

​Error response format

​Status codes

​Common scenarios

​Validation (400)

​Authentication (401)

​Not found (404)

​Rate limited (429)

​Handling errors with the SDK

​Environments

​Support

Error response format

Status codes

Common scenarios

Validation (400)

Authentication (401)

Not found (404)

Rate limited (429)

Handling errors with the SDK

Environments

Support