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

# Error Handling

# 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:

```text theme={null}
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:

| Status | Description                              |
| ------ | ---------------------------------------- |
| 2XX    | Successful operation                     |
| 4XX    | Client or validation error               |
| 5XX    | Temporary 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