Skip to content
ansvra.Documentation
Customer API
Customer API

Errors, limits and retries

Handle failures without duplicating changes or overwhelming your account.

Ansvra reference·5 min read

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.

StatusMeaning and recovery
400Invalid fields, filters, cursor, range or missing Idempotency-Key. Correct the request.
401Missing, invalid, expired or revoked access key. Check or replace the key.
403Missing scope, role/project restriction, inactive paid access or unavailable feature. Review access in Ansvra.
404Resource or operation unavailable to this key. Confirm the identifier and project.
409Conflicting resource, allowance, lifecycle restriction, account lock or reused idempotency key with different content. Resolve the conflict.
408 / 413 / 414 / 415Request timeout, body/response/download too large, query too long or wrong media type. Reduce the request or send application/json.
429Rate or concurrency limit. Wait for Retry-After before retrying.
500 / 503The 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.

Ansvra

A clearer next step.

MEET YOUR AI GUIDE

A little clarity.
A clearer next move.

Ask about Ansvra, AI visibility, or your next step with content.

Opening chat…