Errors and retries
Most request-level errors use error, detail, retryable, and requestId. POST /api/v1/identify and POST /api/v1/enrich can instead return a batch envelope (version, requestId, count, results, and quota) for all-invalid or all-upstream-failed batches. Product reads may return a compact { "error", "requestId" } body. Keep the request ID for support, and do not expose API keys or customer evidence in a support report.
| HTTP status | Meaning | Action |
|---|---|---|
400 |
Invalid input or unsupported selector combination | Correct the request; do not retry unchanged. |
401 |
Missing or invalid API key | Follow setupUrl and steps, or replace the key in the dashboard. |
404 |
Resource or result reference is absent, expired, or inaccessible | Confirm the identifier and account ownership; do not infer a market value. |
409 |
Idempotency conflict, request still running, mapping-selector conflict, or stale mapping revision | Reuse a key only for the identical request body. Resolve conflicts using the response detail. |
413 / 415 |
Body too large or not JSON | Reduce the request or set Content-Type: application/json. |
429 |
Account quota, service safety ceiling, or short-term rate limit | Honor Retry-After; use retryAt when supplied. Do not split batches or create accounts to evade limits. |
502 / 503 |
All required upstream work failed or a required service is unavailable | Preserve any earlier successful identity, retry only when retryable and within a bounded backoff. A provider failure is not a no-match. |
Use one stable Idempotency-Key for each logical paid operation and reuse it only with the identical body on a network retry. A changed body needs a new key. Identical single-product enrich requests without an explicit key replay for 30 seconds. Explicit idempotency records are account-scoped; a pending reservation older than 10 minutes is expired and refunded. A request_expired response is terminal for that key: use a new key only when intentionally starting a new logical operation.
For 429 responses, the beta account allowance counts attempts until monthly plans activate. account_quota_exceeded returns retryAt and Retry-After. daily_limit is the separate service-wide ceiling; rate_limited is a short-term request limit. Read monthly plans for the active policy and account upgrade path. An outage or empty price result must never be represented as $0.