Error Handling

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

HTTP status codes

Status Code	Meaning
200	Success
201	Resource created
400	Bad request (malformed request)
401	Missing API key
402	Subscription required for this feature
403	Invalid or revoked API key
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

The 409 and 422 responses tied to retry handling are described in the idempotency and write validation guide.

Common errors

Authentication error (403)

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

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

Not found (404)

{
  "success": false,
  "errors": {
    "__all__": ["Invoice matching query does not exist."]
  }
}

Rate limit exceeded (429)

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

Developer Guide

V2 (latest)

V1

Release Notes & Changelog

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