Errors — Lumen Sieve Docs

Errors

Every non-2xx response uses the same JSON envelope, so you can write one error handler for the whole API.

Error envelope

Every error response has this shape:

json

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "You've used all the queries included in your plan for this period.",
    "request_id": "req_7516a7ab-9800-4596-ae1a-4eee0b47f666",
    "documentation_url": "https://docs.lumen.com/errors#quota_exceeded",
    "details": { "field": "country_code" }
  }
}

Field	Description
`code`	A stable, machine-readable string — safe to switch on in your code.
`message`	A human-readable explanation, safe to show directly to your own users.
`request_id`	Include this when contacting support — it lets us find the exact request.
`documentation_url`	Deep link to this page for that specific code.
`details`	Optional extra context (e.g. which field was invalid). Not always present.

Tip: Match on error.code, never on error.message — message text can change; codes don't.

Retrying safely

A response is worth retrying (with backoff) when its status is 429 or 5xx, or its code is one of SERVICE_UNAVAILABLE, TIMEOUT. On 429, honor the Retry-After header (seconds) if present rather than guessing a backoff. Everything else — validation errors, auth failures, not-found — will fail again identically on retry; fix the request instead.

400 — Bad request

Code	Meaning
`INVALID_REQUEST`	The request body or query string is malformed.
`MISSING_REQUIRED_FIELD`	A required field was omitted.
`INVALID_FIELD_VALUE`	A field was present but its value is invalid.
`INVALID_BUSINESS_IDENTIFIER`	The business name identifier is invalid.
`INVALID_FIELD_PATH`	The dot-path given for a correction doesn’t match any known field.
`BATCH_TOO_LARGE`	A batch request exceeded the maximum allowed items.
`BATCH_EMPTY`	A batch request had zero items.
`AMBIGUOUS_BUSINESS`	The name/location given matches more than one business — add a locality hint.

401 — Unauthorized

Code	Meaning
`MISSING_AUTH`	No Authorization header was sent.
`INVALID_API_KEY`	The key doesn’t match any active key on file.
`EXPIRED_API_KEY`	The key existed but its expiry date has passed.
`MALFORMED_AUTH`	The Authorization header isn’t a recognizable Bearer token.

403 — Forbidden

Code	Meaning
`INSUFFICIENT_SCOPE`	The key is valid but lacks the scope this endpoint requires.
`ACCOUNT_SUSPENDED`	The account has been suspended — see message for the reason.
`IP_NOT_ALLOWED`	The account has an IP allowlist configured and the caller isn’t on it.
`FEATURE_NOT_AVAILABLE`	The current plan doesn’t include this feature — see the suggested upgrade in the response.
`RESTRICTED_BUSINESS`	The requested business falls under a legal or policy restriction.

404 — Not found

Code	Meaning
`BUSINESS_NOT_FOUND`	No business could be resolved for the given identifier.
`PROFILE_NOT_FOUND`	No profile exists with the given ID.
`BATCH_NOT_FOUND`	No batch job exists with the given ID.
`INVOICE_NOT_FOUND`	No invoice exists with the given ID, or it doesn’t belong to this account.
`NO_DATA_AVAILABLE`	The business was found but Lumen Sieve has no data for the requested field(s).

409 — Conflict

Code	Meaning
`DUPLICATE_REQUEST`	An identical request (same Idempotency-Key) is already being processed.

429 — Too many requests

Code	Meaning
`RATE_LIMIT_EXCEEDED`	Too many requests in a short window — see your plan’s requests-per-minute in Rate limits & plans.
`QUOTA_EXCEEDED`	The account has used its full quota for the current billing period (or lifetime, on the Free plan).
`CONCURRENT_LIMIT_EXCEEDED`	Too many requests in flight at once for this account’s plan.

5xx — Server-side

Code	Status	Meaning
`INTERNAL_ERROR`	500	An unexpected error on Lumen Sieve’s side. Our team is notified automatically.
`EXTRACTION_FAILED`	502	A downstream data source failed in a way that blocked extraction.
`TIMEOUT`	504	The request took longer than the service’s deadline.
`SERVICE_UNAVAILABLE`	503	A downstream service (or a third-party provider like Paddle) is temporarily unreachable.
`PARTIAL_FAILURE`	206	The request partially succeeded — check the response body for which parts failed.
`NOT_IMPLEMENTED`	501	The endpoint exists but this specific capability isn’t enabled yet.