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

# Errors

> The shared error model, status codes, and validation error format used across the Infra API.

All services report failures through the same envelope, so you can handle errors
uniformly regardless of which endpoint you called.

## Error shape

```json theme={null}
{
  "status": false,
  "message": "Wallet not found"
}
```

Validation failures add an `errors` array of field-level messages:

```json theme={null}
{
  "status": false,
  "message": "Validation failed",
  "errors": [
    "webhookUrl: Invalid url"
  ]
}
```

| Field     | Type       | Description                                                 |
| --------- | ---------- | ----------------------------------------------------------- |
| `status`  | `boolean`  | Always `false` on error.                                    |
| `message` | `string`   | Human-readable error summary.                               |
| `errors`  | `string[]` | Optional. Per-field validation messages (`field: message`). |

<Info>
  **Token endpoint is different**

  `POST /v1/oauth/token` returns OAuth 2.0 error bodies (`{ "error", "error_description" }`)
  rather than this envelope. See [Authentication](/getting-started/authentication#token-errors).
</Info>

## Status codes

| Status                     | Meaning            | Typical cause                                                        |
| -------------------------- | ------------------ | -------------------------------------------------------------------- |
| `200 OK`                   | Success            | Request completed.                                                   |
| `201 Created`              | Created            | A new resource (subscription, transfer) was created.                 |
| `202 Accepted`             | Accepted           | Work was queued (e.g. webhook resend).                               |
| `400 Bad Request`          | Invalid input      | Malformed parameter, body, or unsupported value.                     |
| `401 Unauthorized`         | Not authenticated  | Missing/invalid token, or missing project/business context.          |
| `402 Payment Required`     | Insufficient funds | Wallet balance cannot cover estimated gas.                           |
| `403 Forbidden`            | Not authorized     | Test token used, missing capability, or cross-business access.       |
| `404 Not Found`            | No such resource   | Unknown id, or a resource not owned by your project.                 |
| `422 Unprocessable Entity` | Semantic failure   | Validation passed but the operation failed (e.g. transfer reverted). |
| `429 Too Many Requests`    | Rate limited       | Throttle exceeded; honour `retryAfter`.                              |
| `503 Service Unavailable`  | Upstream issue     | Dependency (e.g. gas pricing) temporarily unavailable; retry.        |

## Common error messages

| Status | Message                                                      | Where                            |
| ------ | ------------------------------------------------------------ | -------------------------------- |
| `401`  | `Authorization token is missing or malformed.`               | Any guarded endpoint.            |
| `401`  | `Invalid token`                                              | Token failed verification.       |
| `401`  | `Token is missing project or business context`               | Token lacks the required claims. |
| `403`  | `Test tokens are not allowed, please use your live api key.` | Business endpoints.              |
| `403`  | `Missing required capability: <capability>`                  | Blockchain Events endpoints.     |
| `403`  | `Unauthorized: Cannot access wallet from other business`     | Wallet endpoints.                |
| `404`  | `<Resource> not found`                                       | Lookups by id.                   |

<Tip>
  **Retry strategy**

  Retry `429` after the `retryAfter` interval, and retry `503` after a short backoff.
  Do **not** retry `400`, `401`, `403`, `404`, or `422` without changing the request.
</Tip>