# Errors & limits

## The response envelope

Kwery distinguishes **validation problems** from **infrastructure problems**.

- **Validation problems** are returned with **HTTP 200** and an `"error": true` body. Always
check the `error` field before consuming a response:

```json
{ "error": true, "message": "country not supported by source" }
```
- **Infrastructure problems** use standard HTTP status codes:
| Status | Meaning |
|  --- | --- |
| `401` | Missing or invalid credentials. |
| `403` | Authenticated, but not allowed (e.g. accessing another account's job). |
| `503` | Server under load — retry after the `Retry-After` interval. |


Common validation messages include `not subscribed to source`, `country not supported by source`, `parameter missing`, `parameter value invalid`, and `job not found`. Per-value
problems (e.g. a bad GTIN checksum) are reported on that value's result as
`success: false` with a `reason`, rather than failing the whole job.

## Per-result fields

Each result in a download or stream delivery has:

| Field | Description |
|  --- | --- |
| `key` | The `key:value` this result is for. |
| `success` | `true` if the lookup completed (including a clean "not found"). |
| `reason` | Present when relevant — e.g. `not found`. |
| `content` | The parsed product/offer data (source-specific — see [Sources](/sources)). |
| `index` | 0-based position in the submitted `values[]` (stream results). |


## Limits

| Limit | Value |
|  --- | --- |
| Batch values per job | **1 000** |
| Stream values per job | **100 000** |
| Stream results per polling page | **1 000** (`limit`) |
| Result retention | **72 hours** |


Results are retained for 72 hours after completion; download or consume them within that
window.

## Rate limiting

There is no fixed per-account request-rate limit today. Under heavy system load the API may
return `503` with a `Retry-After` header — back off and retry. If you plan a very large or
sustained workload, talk to us first so we can size capacity.

## See also

- [Authentication](/guides/authentication) — the `not subscribed to source` error and the
subscription model.
- [Getting started](/guides/getting-started) — the happy path.