> ## Documentation Index > Fetch the complete documentation index at: https://docs.nxos.io/llms.txt > Use this file to discover all available pages before exploring further. # Errors > Error response format and error codes. ## Error format All errors follow a consistent envelope: ```json theme={null} { "error": { "code": "account_not_found", "message": "Account not found.", "requestId": "req_abc123" } } ``` | Field | Description | | ----------- | ------------------------------------------------------------------------------------------------------- | | `code` | Machine-readable error code. Use this for programmatic handling. | | `message` | Human-readable description. Intended for developers, not end users. Messages may change without notice. | | `requestId` | Unique request identifier. Include this when contacting support. | ## HTTP status codes | Status | Meaning | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `400` | Bad request — invalid syntax, missing required fields, or validation failure. | | `401` | Unauthorized — missing or invalid API key. | | `403` | Forbidden — the API key is valid but lacks permission for this action. | | `404` | Not found — the requested resource does not exist, or does not belong to your organization. | | `409` | Conflict — the action conflicts with the resource's current state (e.g., archiving an already-archived beneficiary, executing an expired quote). | | `422` | Unprocessable entity — the request body failed schema validation. | | `429` | Too many requests. Your organization exceeded its rate limit. See [Idempotency and rate limits](/concepts/idempotency-and-rate-limits). | | `500` | Internal error — something went wrong on our end. Retry the request. | | `502` | Upstream error — a dependent service failed (e.g., blockchain node). Retry the request. | ## Error codes ### Authentication | Code | HTTP | Description | | ------------------------ | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `missing_api_key` | 401 | No `Authorization` header, or it doesn't start with `Bearer `. | | `invalid_api_key` | 401 | The key doesn't exist or has been revoked. | | `authentication_failed` | 401 | Key verification failed due to a server error. Retry. | | `forbidden` | 403 | API key is valid but not authorized for this action. | | `acting_org_not_found` | 403 | The `Nxos-On-Behalf-Of` header points to an organization that does not exist. | | `authorization_required` | 403 | The `Nxos-On-Behalf-Of` target exists, but your organization holds no active authorization (LOA) on it. See [Cross-org access](/guides/cross-org-access). | ### Resource lookup | Code | HTTP | Description | | -------------------------- | ---- | ----------------------------------------------------------------------- | | `not_found` | 404 | Generic resource not found. | | `organization_not_found` | 404 | Organization does not exist. | | `account_not_found` | 404 | Account does not exist or does not belong to your organization. | | `quote_not_found` | 404 | Quote does not exist. | | `beneficiary_not_found` | 404 | Beneficiary does not exist or does not belong to the specified account. | | `transaction_not_found` | 404 | Transaction does not exist or is not on one of your accounts. | | `funding_method_not_found` | 404 | Funding method does not exist or does not belong to your organization. | | `authorization_not_found` | 404 | The referenced authorization (LOA) grant does not exist. | | `nxosnet_handle_not_found` | 404 | No NXOS organization matches the supplied nxosnet handle. | ### Business logic | Code | HTTP | Description | | ------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------- | | `quote_expired` | 409 | The quote has expired. Create a new one. | | `quote_already_used` | 409 | The quote has already been executed. | | `beneficiary_already_archived` | 409 | The beneficiary is already archived. | | `beneficiary_not_archived` | 409 | The beneficiary is not archived, so it cannot be restored. | | `beneficiary_blocked` | 409 | The beneficiary is blocked for compliance reasons and cannot be used. | | `nxosnet_not_enabled` | 409 | The target organization has not enabled NXOS-to-NXOS transfers. | | `fee_schedule_drifted` | 409 | The fee schedule changed since the quote was issued. Re-quote and retry. | | `idempotency_key_in_use` | 409 | The supplied `Idempotency-Key` was previously used with a different request body. Use a unique key per logical operation. | | `idempotency_request_in_flight` | 409 | A request with the same `Idempotency-Key` is currently being processed. Retry shortly. | | `insufficient_funds` | 400 | The account does not have enough balance for this operation. | ### Validation and system | Code | HTTP | Description | | --------------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `validation_error` | 422 | Request body failed schema validation. Check the `message` for details. | | `invalid_request` | 400 | The request is malformed or contains invalid parameters. | | `share_token_invalid` | 400 | The supplied verification share token is invalid or expired. | | `verification_import_unsupported` | 400 | Verification import is not supported for the supplied provider or payload. | | `rate_limited` | 429 | Your organization exceeded its request quota. Wait for the `Retry-After` header before retrying. See [Idempotency and rate limits](/concepts/idempotency-and-rate-limits). | | `chain_send_failed` | 502 | The on-chain transaction could not be submitted. | | `webhooks_unavailable` | 502 | The webhooks service is temporarily unavailable. Retry the request. | | `internal_error` | 500 | Unexpected server error. Retry the request. | ## Handling errors ```javascript theme={null} const response = await fetch('https://api.sandbox.nxos.io/v1/quotes', { method: 'POST', headers: { 'Authorization': 'Bearer nxos_sk_test_...', 'Content-Type': 'application/json', }, body: JSON.stringify({ /* ... */ }), }); if (!response.ok) { const { error } = await response.json(); switch (error.code) { case 'insufficient_funds': // Handle insufficient balance break; case 'validation_error': // Handle invalid input break; default: // Log requestId for debugging console.error(`API error: ${error.code} (${error.requestId})`); } } ``` Always include the `requestId` when reporting issues. It lets us trace the exact request through our systems.