Skip to main content

​
Error Handling

The Nexbridge Partner API returns structured errors for:
  • validation failures
  • operational restrictions
  • lifecycle violations
  • authentication failures
Partners should always validate API responses before assuming successful processing.

​
Error Categories

​
Authentication Errors

Authentication errors occur when:
  • the API Key is missing
  • the API Key is invalid
  • the API Key is suspended
  • the API Key is revoked
Authentication failures reject the request immediately.

​
Validation Errors

Validation errors occur when request parameters are invalid. Examples include:
  • unsupported asset
  • unsupported network
  • invalid address
  • invalid precision
  • malformed request payload
Validation failures prevent request creation or processing.

​
Operational Errors

Operational errors occur when the request is operationally incompatible with the current lifecycle or platform rules. Examples include:
  • expired quote
  • inactive address
  • unsupported request state
  • invalid settlement configuration
  • operational restrictions

​
Lifecycle Errors

Lifecycle errors occur when an operation is attempted in an invalid lifecycle state. Examples include:
  • cancelling a fulfilled request
  • reusing a consumed quote
  • using an expired quote
  • referencing inactive addresses

​
Funding Errors

Funding-related errors may occur when:
  • funding originates from a non-approved source
  • funding uses an unsupported asset
  • funding is operationally incompatible
  • funding validation fails
Funding validation failures may transition funding to: 
DIRTY

​
Retry Behavior

Partners should implement retry logic carefully. Safe retry scenarios may include:
  • temporary network failures
  • temporary availability issues
  • timeout scenarios
Partners should avoid blind retries for:
  • validation failures
  • lifecycle violations
  • operational restrictions

​
Idempotency Recommendation

Partners are encouraged to implement idempotent request handling. This helps avoid duplicated requests caused by:
  • retries
  • timeouts
  • connectivity interruptions

​
Error Responses

Error responses may include:
  • HTTP status code
  • error code
  • error message
  • operational details
Exact response schemas are documented separately in the API Reference.

​
HTTP Status Expectations

Typical HTTP status categories include:
StatusDescription
2XXSuccessful operation
4XXClient or validation error
5XXTemporary server or infrastructure error

​
Operational Visibility

Partners should monitor:
  • request lifecycle
  • funding lifecycle
  • balance visibility
instead of relying exclusively on synchronous responses. Many operations are asynchronous by nature.

​
Future Scope

The following capabilities are currently out of scope for V1:
  • webhook-based error notifications
  • advanced retry orchestration
  • dead-letter handling
  • partner-configurable retry policies
  • async reconciliation callbacks