> ## 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 format, HTTP status codes, retries, and what to show users.

## 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 |
| - | - | - |
| `201` | Resource created (quotations and orders) | Not an error |
| `400` | Validation error, missing field, business rule violation | No. Fix the request first |
| `401` | Authentication failed (`AUTH_*` codes) | No. Check the key, timestamp 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

### Authentication failure

A missing header, an expired timestamp, an unknown key or a signature that doesn't verify. These return HTTP `401` with an `AUTH_*` code. See [authentication errors](/guides/development-and-testing/authentication#authentication-errors) for every code and its fix.

```json theme={null}
{
  "status": false,
  "message": "Invalid Signature",
  "data": null,
  "errors": {},
  "err_code": "AUTH_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@zapyd.com](mailto:support@zapyd.com) with the request ID and timestamp.