Docs / Errors
Error reference
Every error the API returns is a JSON object with an error field and an appropriate HTTP status. Below are the status codes we use and how to recover from each.
400
Bad Request
- When
- Missing `invoiceData`, malformed JSON, or invalid enum values (incoterms, currency, transport).
- How to recover
- Validate the payload against the Quickstart example. `invoiceData.lineItems[]` must have at least one entry.
401
Unauthorized
- When
- Authorization header missing, malformed, or the bearer token is not a valid active API key.
- How to recover
- Confirm the header is `Authorization: Bearer cik_…`. If the key was revoked, mint a new one at /settings/api-keys.
404
Not Found
- When
- The resource (e.g. an invoice id passed to a future GET endpoint) does not exist or is not owned by your account.
- How to recover
- Double-check the id. Invoice ids are UUIDs; short ids look like INV-2026-ABC123.
413
Payload Too Large
- When
- Invoice JSON exceeds 1 MB or contains more than ~500 line items.
- How to recover
- Split the shipment into multiple invoices or reduce redundant fields.
429
Too Many Requests
- When
- Rate limit hit (60 invoices per hour per API key).
- How to recover
- Retry after the next rolling window. For higher throughput, request an increased limit at hello@customs-invoice.com.
500
Internal Server Error
- When
- Unexpected failure on our side. The invoice record may still have been created — check `/invoices` in the dashboard.
- How to recover
- Retry with exponential backoff. If the issue persists, include the returned `id` (if present) when contacting support.
503
Service Unavailable
- When
- Backend is temporarily unavailable (maintenance, infrastructure outage, or missing env on a self-hosted deployment).
- How to recover
- Retry after 30–60 seconds. Subscribe to status updates via the status page.
Retry strategy: 5xx errors are retryable with exponential backoff (start at 1s, double up to 30s, cap at ~8 attempts). 4xx errors are not retryable without changing the request.