# Errors

API errors use a stable JSON shape after authentication succeeds.

```json
{
  "error": {
    "code": "unsupported_asset",
    "message": "Mock API supports only bsc-usdt and bsc-usdc on bsc-mainnet"
  }
}
```

## Common HTTP Statuses

| HTTP status | Meaning                                                                                      |
| ----------- | -------------------------------------------------------------------------------------------- |
| `400`       | Request validation failed.                                                                   |
| `401`       | Missing or invalid bearer token. This can be returned by the gateway before the API handler. |
| `404`       | Resource was not found.                                                                      |
| `409`       | Idempotency key or business identifier conflict.                                             |
| `501`       | Endpoint exists but real non-mock implementation is not enabled yet.                         |

## Common Error Codes

| Code                                            | HTTP status | Meaning                                                        |
| ----------------------------------------------- | ----------- | -------------------------------------------------------------- |
| `missing_idempotency_key`                       | `400`       | A mutation request did not include `Idempotency-Key`.          |
| `invalid_idempotency_key`                       | `400`       | The idempotency key is not 8 to 128 visible ASCII characters.  |
| `invalid_pay_with`                              | `400`       | Current payment creation requires exactly one `pay_with` item. |
| `invalid_mock_scenario`                         | `400`       | `X-Artum-Mock-Scenario` is not supported.                      |
| `unsupported_chain`                             | `400`       | The chain is not supported by the mock registry.               |
| `unsupported_asset`                             | `400`       | The asset is not supported by the mock registry.               |
| `mock_scenario_not_supported`                   | `400`       | A mock scenario header was sent outside mock mode.             |
| `payment_not_found`                             | `404`       | The payment ID does not exist in current mock state.           |
| `chain_not_found`                               | `404`       | The chain key does not exist in the registry.                  |
| `order_id_conflict`                             | `409`       | A payment with this `order_id` already exists.                 |
| `idempotency_key_reused_with_different_payload` | `409`       | The key was already used with a different request body.        |
| `not_implemented`                               | `501`       | Real non-mock behavior is not active yet.                      |
| `internal_error`                                | `500`       | Unexpected API error.                                          |

## Handling Guidance

Treat `400` as a client integration bug unless the user can fix the input.

Treat `409` idempotency conflicts as a retry implementation bug.

Treat `404 payment_not_found` in mock as possible mock state reset if the payment existed earlier.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.artum.app/payments/errors.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.