> ## Documentation Index
> Fetch the complete documentation index at: https://developers.bumxpress.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Understand the standard merchant API error shape and common HTTP statuses.

Merchant API errors use a consistent JSON shape:

```json theme={null}
{
  "error": {
    "code": "bad_request",
    "message": "quote_id is required"
  }
}
```

## HTTP statuses

| Status | Meaning                                                                              |
| ------ | ------------------------------------------------------------------------------------ |
| `400`  | Invalid body, missing field, expired quote, quote mismatch, or insufficient balance. |
| `401`  | Missing, invalid, expired, or inactive API credentials.                              |
| `404`  | Resource not found for the authenticated merchant.                                   |
| `409`  | Idempotency conflict or a request with the same key is still processing.             |

## Handling recommendations

* Show actionable validation errors to your operators or support team.
* Retry network failures with the same `Idempotency-Key` only when the business intent and request body are unchanged.
* Do not retry authentication errors until credentials have been fixed.
* Store error responses with your internal payment record for reconciliation and support.