> ## Documentation Index
> Fetch the complete documentation index at: https://api.nektir.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and limits

> Handle validation, cursor, rate-limit, and availability failures.

Errors use `application/problem+json` and include:

```json theme={"dark"}
{
  "type": "https://example.invalid/problems/bad_request",
  "title": "Invalid request",
  "status": 400,
  "detail": "lat and lng must be supplied together",
  "instance": "/v1/stores",
  "code": "INVALID_PARAMETER",
  "request_id": "018f2fd0-a3d4-7d20-9c11-9482722f6b26",
  "invalid_params": [
    { "name": "lat", "reason": "must be supplied with lng" }
  ]
}
```

| Status | Handling                                                                                                                  |
| ------ | ------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Correct the invalid or incompatible parameters.                                                                           |
| `404`  | The route or published resource does not exist.                                                                           |
| `410`  | Restart pagination without the expired cursor.                                                                            |
| `429`  | Wait for `Retry-After`, then retry with jitter.                                                                           |
| `500`  | Retry only if appropriate and retain `request_id` when reporting the failure. Internal details are deliberately withheld. |
| `503`  | Keep last-known-good application state and retry with exponential backoff.                                                |

Every response includes `X-Request-ID`; error bodies repeat it as `request_id`. This is the value an API consumer should include in a support report.

## Data warnings

Successful responses can include structured `meta.warnings`. These are not transport errors and should not be hidden:

| Code                           | Meaning                                                                                                                                                                         |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FIXTURE_DATA`                 | The published inventory is historical fixture evidence, not current DABS inventory.                                                                                             |
| `INVENTORY_COVERAGE_PARTIAL`   | Unchecked product/store pairs remain; an empty result does not establish no stock.                                                                                              |
| `UPSTREAM_UPDATE_TIME_UNKNOWN` | Nektir knows when it retrieved the response, but DABS did not provide when its underlying data changed.                                                                         |
| `SOURCE_REFRESH_DELAYED`       | A scheduled attempt is overdue or failed; the API is retaining the last successful observation.                                                                                 |
| `UPSTREAM_PRODUCT_UNAVAILABLE` | DABS itself currently fails to serve the product detail. Inventory stays unchecked or last-known-good, and automated retries are paused after operator confirmation.            |
| `SOURCE_SCHEMA_QUARANTINED`    | Automatic refresh stopped because identity or response structure did not validate.                                                                                              |
| `CATALOG_BATCH_OLD`            | The latest complete catalog batch exceeds the configured catalog retrieval-age policy. This code is reserved for catalog-age monitoring and is not inferred from inventory age. |

Inventory objects separately expose their last successful `times.retrieved_at`, Nektir `times.published_at`, and `last_refresh_attempt`. A recent failed attempt never replaces the successful observation timestamp.

The local pilot default is 300 public requests per minute per client address. An online deployment may enforce the same policy at its trusted edge instead. Treat the published `Retry-After` header as authoritative if deployment policy changes.