# Errors

The API uses standard HTTP status codes. Error bodies are JSON, with two shapes.

**Message errors** (`401`, `403`, `404`, `429`) carry a `detail` string:

```json
{"detail": "Invalid API key"}
```

**Validation errors** (`400`) map each invalid field to a list of messages. Errors not tied to one field appear under `non_field_errors`; nested objects and lists follow the same shape:

```json
{
  "end_of_day": ["Datetime has wrong format. Use one of these formats instead: YYYY-MM-DDThh:mm[:ss[.uuuuuu]][+HH:MM|-HH:MM|Z]."],
  "non_field_errors": ["Either a filter, an address or a polygon must be provided"]
}
```

The SiftMap add-properties endpoints wrap validation errors differently:

```json
{"success": false, "message": "an error occurred during the validation of input data, try again later.", "details": {"ids": ["This field is required."]}}
```

## Status codes

| Code | Meaning | Example `detail` | What to do |
|  --- | --- | --- | --- |
| 200 / 201 | Success |  | Verify the outcome with a read (see [Conventions](/guides/conventions)) |
| 204 | Success, no body |  |  |
| 400 | Validation failed | field messages | Fix the named fields and resend |
| 401 | Missing or invalid key | `Authentication credentials were not provided.` / `Invalid API key` | Send `Authorization: Api-Key YOUR_OPEN_API_KEY`; check the key wasn't revoked |
| 403 | Not allowed | `You do not have permission to perform this action.` | The key's user lacks the permission, or the plan lacks the feature |
| 404 | Not found | `No Property matches the given query.` | Check the path and uuid; the record may belong to another account |
| 405 | Method not allowed | `Method "OPTIONS" not allowed.` | Check the method in the API reference |
| 409 | Conflict |  | Read the current state, then reconcile |
| 429 | Rate limited | `Request was throttled. Expected available in 37 seconds.` | Wait that many seconds (or the `Retry-After` header), then retry |
| 5xx | Server error | (body may be HTML) | Retry with exponential backoff; report it if it persists |


## Handling errors in code

- **Log the response body** of every non-`2xx` response. Validation messages name the exact field.
- **Don't retry `400`, `401`, `403` or `404`.** The same request will fail again.
- **Retry `429`** after the wait in the message, and **`5xx`** with exponential backoff and jitter (for example 1 s, 2 s, 4 s, 8 s, then give up).
- **Expect HTML on `5xx`.** Some server errors return an HTML page instead of JSON, so check `Content-Type` before parsing.
- **A `2xx` isn't proof.** Read back what you wrote; see [Conventions](/guides/conventions).


```python
import time, requests

def call(method, url, headers, retries=4, **kwargs):
    for attempt in range(retries + 1):
        r = requests.request(method, url, headers=headers, timeout=30, **kwargs)
        if r.status_code == 429:
            wait = int(r.headers.get("Retry-After", 0)) or int("".join(c for c in r.json().get("detail", "") if c.isdigit()) or 30)
            time.sleep(wait + 1)
        elif r.status_code >= 500 and attempt < retries:
            time.sleep(2 ** attempt)
        else:
            return r
    return r
```