Error Handling

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

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 for the documented response code.

Error response format

All errors follow this structure:

{
  "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.

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 covers both cases.

{
  "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.

{
  "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:

{
  "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:

{
  "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."
}

Not found (404)

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

{
  "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 covers the limits and how to use the Retry-After header:

{
  "success": false,
  "errors": {
    "__all__": ["Rate limit exceeded. Please try again later."]
  }
}

Handling errors

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.

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

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 →

Get Started

API

Command-Line Interface

Integrations & Tools

HTTP status codes

Error response format

Common errors

Authentication error (403)

Subscription required (402)

Validation error (422)

Not found (404)

Rate limit exceeded (429)

Handling errors

Retrying safely with idempotency keys

Example

​HTTP status codes

​Error response format

​Common errors

​Authentication error (403)

​Subscription required (402)

​Validation error (422)

​Not found (404)

​Rate limit exceeded (429)

​Handling errors

​Retrying safely with idempotency keys

​Example

HTTP status codes

Error response format

Common errors

Authentication error (403)

Subscription required (402)

Validation error (422)

Not found (404)

Rate limit exceeded (429)

Handling errors

Retrying safely with idempotency keys

Example