Error format
All errors follow a consistent envelope:{
"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. |
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. |
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. |
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
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.