> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.defdex.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.defdex.io/_mcp/server.

# Errors and retries

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

```json
{"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](mailto: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.