On this page
Errors, limits and retries
Handle failures without duplicating changes or overwhelming your account.
Handle errors
Errors use { error: { code, message, requestId } }. Check the HTTP status first, then the code. Keep the requestId when contacting support. Responses do not include database traces or credentials.
| Status | Meaning and recovery |
|---|---|
| 400 | Invalid fields, filters, cursor, range or missing Idempotency-Key. Correct the request. |
| 401 | Missing, invalid, expired or revoked access key. Check or replace the key. |
| 403 | Missing scope, role/project restriction, inactive paid access or unavailable feature. Review access in Ansvra. |
| 404 | Resource or operation unavailable to this key. Confirm the identifier and project. |
| 409 | Conflicting resource, allowance, lifecycle restriction, account lock or reused idempotency key with different content. Resolve the conflict. |
| 408 / 413 / 414 / 415 | Request timeout, body/response/download too large, query too long or wrong media type. Reduce the request or send application/json. |
| 429 | Rate or concurrency limit. Wait for Retry-After before retrying. |
| 500 / 503 | The request could not complete or access is temporarily unavailable. Retry with backoff; keep the request ID if it persists. |
Respect request limits
Per minute: 120 requests per key and 300 per account; configuration changes also share a 30-per-account limit. Reports, draft research and downloads share a 20-per-account limit and a maximum of three concurrent requests. Limits are shared across your keys.
Read X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset when present. Reset is seconds until the window resets. A 429 can include Retry-After in seconds. Network protection can also return a 429 without the JSON error envelope. Apply exponential backoff with jitter; do not retry validation or permission failures unchanged.
Keep requests bounded
JSON bodies are limited to 128 KiB, queries to 8,192 characters and JSON responses to 4 MiB. A request has a bounded processing time of approximately 30 seconds. Reduce page sizes or reporting ranges when needed. Keep secrets in headers, never URLs.
Retry creation safely
Every POST requires an Idempotency-Key header, 1–128 characters using letters, numbers, dots, underscores, colons or hyphens. Give each distinct creation a new key. Reuse the same key and identical request when retrying that creation. Successful creations are remembered for 24 hours for that access key; a retry returns the original response without creating another record. Reusing it with different content returns 409. Authorization is checked again on retries.
PATCH requests preserve fields you omit and do not require this header. For POST timeouts or connection failures, retry with the original Idempotency-Key. Never use one constant key for every new record.