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

# Error Handling

> Understand DualEntry Public API errors: standard HTTP status codes and a consistent JSON error format, with the meaning of each code.

The API uses standard HTTP status codes and returns errors in a consistent JSON format.

## HTTP status codes

Every response carries one of these status codes. Check the code first, then read the response body for details:

| Status Code | Meaning |
| - | - |
| `200` | Success |
| `201` | Resource created |
| `400` | Bad request (malformed request) |
| `402` | Subscription required for this feature |
| `403` | Missing, invalid, or revoked API key, or the key's roles do not permit the operation |
| `404` | Resource not found |
| `409` | Conflict (a write with the same `Idempotency-Key` is still in flight, or its response cannot be replayed) |
| `422` | Validation error |
| `429` | Rate limit exceeded |
| `500` | Server error |
| `503` | Service unavailable |

> [!NOTE]
>
> Create endpoints do not all return the same status code. Transaction and record endpoints (for example `POST /public/v2/bills/`) return `200`; master-data endpoints (for example `POST /public/v2/customers/`) return `201`. Check the specific endpoint in the [API reference](https://docs.dualentry.com/developers/api/resources-v2/invoices/list-invoice-records.md) for the documented response code.

## Error response format

All errors follow this structure:

```json theme={null}
{
  "success": false,
  "errors": {
    "<field_name|__all__>": ["error message"]
  }
}
```

* `errors.__all__`: General errors not specific to a field
* `errors.<field_name>`: Errors specific to a particular field

Some errors also carry two top-level fields alongside `errors`:

* `error_code` (string, optional): Stable identifier of the error
* `error_reason` (string, optional): General explanation of the error

The `409` and `422` responses tied to retry handling are described in the [idempotency and write validation guide](https://docs.dualentry.com/developers/guides/api/core-concepts/idempotency-and-write-validation.md).

## Common errors

### Authentication error (403)

Returned when the `X-API-KEY` header is missing or empty, or the key is unknown or revoked. A key that authenticates but lacks the roles for the operation also returns `403`, with `Access denied` as the message. [Authentication](https://docs.dualentry.com/developers/guides/api/authentication.md) covers both cases.

```json theme={null}
{
  "success": false,
  "errors": {
    "__all__": ["API key authentication failed"]
  }
}
```

### Subscription required (402)

Returned when your organization does not have the subscription required for the requested feature.

```json theme={null}
{
  "success": false,
  "errors": {
    "__all__": ["Subscription required for this feature"]
  }
}
```

### Validation error (422)

Returned when the request body fails validation. Each key in `errors` names a field that failed, with the reasons as a list:

```json theme={null}
{
  "success": false,
  "errors": {
    "customer_id": ["Customer with this ID does not exist"],
    "date": ["Invalid date format. Use ISO 8601 format (YYYY-MM-DD)"],
    "lines": ["At least one line item is required"]
  }
}
```

An example with `error_code` and `error_reason`, from a write in a locked accounting period:

```json theme={null}
{
  "success": false,
  "errors": {
    "__all__": ["Record is in the locked period (AP). Company: Acme Corp"]
  },
  "error_code": "period_locked",
  "error_reason": "The request changes data in a locked accounting period."
}
```

An edit or archive of a posted record in a company where [Lock posted accounting records](https://docs.dualentry.com/accountants/platform-configuration/organization-settings/general-preferences.md#lock-posted-accounting-records) is on returns `422` with the error code `posted_record_immutable`. The message names the record type. The same request succeeds again only after an **Administrator** removes the record's company from the lock, so correct the record by posting an offsetting record instead of retrying:

```json theme={null}
{
  "success": false,
  "errors": {
    "__all__": ["Cannot modify posted Bill while posted-record immutability is enabled."]
  },
  "error_code": "posted_record_immutable",
  "error_reason": "The record is posted, and the organization does not allow changes to posted records."
}
```

### Not found (404)

Returned when no record matches the ID or number in the request path:

```json theme={null}
{
  "success": false,
  "errors": {
    "__all__": ["Invoice matching query does not exist."]
  }
}
```

### Rate limit exceeded (429)

Returned when the API key exceeds its rate limit. [Rate limiting](https://docs.dualentry.com/developers/guides/api/core-concepts/rate-limiting.md) covers the limits and how to use the `Retry-After` header:

```json theme={null}
{
  "success": false,
  "errors": {
    "__all__": ["Rate limit exceeded. Please try again later."]
  }
}
```

## Handling errors

> [!NOTE]
>
> **Best Practices**:
>
> * Always check HTTP status codes
> * Parse the `errors` object for field-specific details
> * Implement retry logic for rate limits (`429`) and server errors (`5xx`)
> * Use the `Idempotency-Key` header so retries do not create duplicate records
> * Log error responses for debugging

## Retrying safely with idempotency keys

Write requests (`POST`, `PUT`, `PATCH`, `DELETE`) accept an optional `Idempotency-Key` header so a retry after a network error or timeout does not create a duplicate record.

* Send a unique value in the `Idempotency-Key` header on the original request. A UUID works well.
* If you retry with the same key, the API replays the original response instead of processing the request again. No duplicate record is created.
* Replays are available for **48 hours** after the original request. After that window, the key is forgotten and a retry with the same key is treated as a new request.
* Reusing the same key with a different request body returns `422`. Either use a new key for the new request, or send the exact same body.

```bash theme={null}
curl -X POST https://api.dualentry.com/public/v2/bills/ \
  -H "X-API-KEY: your_api_key_here" \
  -H "Idempotency-Key: 9f8a7b6c-1234-4d5e-9f01-abcdef012345" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

### Example

```python theme={null}
response = requests.post(url, headers=headers, json=data)

if response.status_code in (200, 201):
    # Success, 200 for record endpoints, 201 for master-data endpoints
    result = response.json()
elif response.status_code == 402:
    # Subscription not enabled for this feature
    print(response.json()["errors"]["__all__"])
elif response.status_code == 422:
    # Validation errors
    errors = response.json()["errors"]
    for field, messages in errors.items():
        print(f"{field}: {messages}")
elif response.status_code == 429:
    # Rate limited - wait and retry
    time.sleep(60)
    response = requests.post(url, headers=headers, json=data)
else:
    # Other error
    print(f"Error {response.status_code}: {response.json()}")
```

***

**Next:** [Explore the API Reference →](https://docs.dualentry.com/developers/api/resources-v2/invoices/list-invoice-records.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.