Errors - Nxos

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.

​Error format

​HTTP status codes

​Error codes

​Authentication

​Resource lookup

​Business logic

​Validation and system

​Handling errors

Error format

HTTP status codes

Error codes

Authentication

Resource lookup

Business logic

Validation and system

Handling errors