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

# Error handling

> Error formats, HTTP status codes, retry strategy, and what to show users vs what to log.

## Error response format

All API errors follow the same structure:

```json theme={null}
{
  "status": false,
  "message": "Bad Request",
  "data": null,
  "err_code": "INPUT_MALFORMED",
  "errors": {
    "field_name": ["Error message"]
  }
}
```

* `err_code`: machine-readable code for programmatic handling
* `errors`: field-level detail, present on validation errors
* `message`: human-readable summary

***

## HTTP status codes

| Code  | Meaning                                                  | Retryable                            |
| ----- | -------------------------------------------------------- | ------------------------------------ |
| `400` | Validation error, missing field, business rule violation | No. Fix the request first            |
| `401` | Invalid or missing API credentials                       | No. Check your API key and signature |
| `404` | Resource not found or endpoint doesn't exist             | No. Check the ID or URL              |
| `429` | Rate limit exceeded                                      | Yes. Back off and retry              |
| `500` | Unexpected server error                                  | Yes. Retry with exponential backoff  |

### Retry strategy

For `429` and `5xx` responses, retry with exponential backoff:

* Wait 1s before the first retry
* Double the wait on each subsequent attempt
* Cap at 30s
* Stop after 3 to 5 attempts and alert your team

For `4xx` responses, retrying the same request will not help. Fix the request first.

***

## What to show users vs what to log

| Error type                                       | Show to user                                     | Log internally                                |
| ------------------------------------------------ | ------------------------------------------------ | --------------------------------------------- |
| Field validation (`400` with `errors`)           | Yes, show the relevant field message             | Yes                                           |
| Business rule violation (`400`, no field errors) | Yes, generic "this action couldn't be completed" | Yes, with full error body                     |
| Auth failure (`401`)                             | No, show "something went wrong"                  | Yes, check for key expiry or misconfiguration |
| Not found (`404`)                                | Only if the resource is user-facing              | Yes                                           |
| Rate limit (`429`)                               | No, retry silently                               | Yes                                           |
| Server error (`500`)                             | Yes, "something went wrong, try again shortly"   | Yes, alert your team                          |

Never expose `err_code` or raw error bodies to end users.

***

## Error categories

### Malformed request

Invalid JSON, bad headers, or a signature that doesn't verify.

```json theme={null}
{
  "status": false,
  "message": "Bad Request",
  "data": null,
  "err_code": "INPUT_MALFORMED",
  "errors": {
    "signature": ["Invalid Signature"]
  }
}
```

### Object not found or access denied

The resource doesn't exist or doesn't belong to your organization.

```json theme={null}
{
  "status": false,
  "message": "Bad Request",
  "data": null,
  "err_code": "USR_UNVERIFIED",
  "errors": {
    "customer": ["Customer not found or access denied."]
  }
}
```

### Missing required fields

A required field was omitted from the request body.

```json theme={null}
{
  "status": false,
  "message": "Bad Request",
  "data": null,
  "err_code": "REQ_FIELD_MISSING",
  "errors": {
    "customer_id": ["This field is required."],
    "tax_number": ["This field is required."]
  }
}
```

### Blank field value

A field was included but left empty.

```json theme={null}
{
  "status": false,
  "message": "Bad Request",
  "data": null,
  "err_code": "INPUT_MALFORMED",
  "errors": {
    "customer_id": ["This field may not be blank."]
  }
}
```

### Format or length violation

A field value doesn't match the expected format or exceeds length limits.

```json theme={null}
{
  "status": false,
  "message": "Bad Request",
  "data": null,
  "err_code": "INPUT_MALFORMED",
  "errors": {
    "email": ["Enter a valid email address."],
    "name": ["Ensure this field has no more than 255 characters."]
  }
}
```

### Business rule violation

The request is valid but conflicts with a business constraint.

```json theme={null}
{
  "status": false,
  "message": "Bad Request",
  "data": null,
  "err_code": "INPUT_MALFORMED",
  "errors": {
    "transaction": ["Transaction hash already linked to a payout"],
    "email": ["Email already in use."]
  }
}
```

### Server error

```json theme={null}
{
  "success": false,
  "message": "Internal Server Error",
  "err_code": "SYS_INTERNAL_ERROR",
  "errors": "Unexpected error occurred. Please try again later.",
  "data": null
}
```

Retry with backoff. If it persists, contact [support@dollarpe.xyz](mailto:support@dollarpe.xyz) with the request ID and timestamp.