Errors and retries

A failed API request returns a JSON object with an error message, for example:

{"error":"Invalid or revoked API key"}

Check HTTP status and the response body before interpreting an empty result. Preserve X-Request-Id when present. It identifies admitted requests; early authentication or admission failures may have no request ID. Redact authorization headers in diagnostics.

Diagnose the status

Status	What to do
400	Check field names, typed values, required filters and cursor. For a query-budget error, add exact filters.
401	Check Bearer syntax and whether the key is missing, invalid or revoked.
403	Check the key’s scope. A scope change requires an appropriately scoped key.
404	Check the dataset and exact ID. Another account’s proposal also returns 404.
405	Use a supported method. Published data reads use GET; correction submission uses POST.
409	Read the message: restart build-bound pagination/relist positional records, or fix conflicting correction idempotency content.
413	Reduce the correction JSON body below 16 KB.
429	For request-rate limits, obey Retry-After. For correction storage caps, wait for capacity or the rolling-day window.
503	Dependency/service temporarily unavailable; a bounded retry may help.

A 200 response with data: [] is a valid query with no matches. Remove filters one at a time, verify exact IDs/types, and distinguish unpublished data from absence in the real world. Null, zero, false, missing values and empty lists have different meanings.

Retry deliberately

The SDKs and CLI do not retry automatically or follow redirects. Use the documented canonical HTTPS base URL; do not forward your key to another host.

For GET reads, use a bounded policy: wait Retry-After when supplied; otherwise use exponential backoff with jitter for transient 503/network failures, for example up to three attempts. Stop and surface the error when the retry budget is exhausted. Do not retry 400/401/403/404 unchanged. Do not advance the cursor after failure.

For correction submissions, keep the same idempotency key and same proposal when retrying an uncertain result. Changing the body under a stored key returns 409. If you change the proposal intentionally, generate a new key. Retrying still counts toward admitted request usage.

Report an issue

Contact support@defdex.io with the UTC time, endpoint, HTTP status, sanitized error and request ID when available. Include relevant dataset, record ID and build ID. Never include an API key, session cookie or password.