# Errors

The Product API uses standard HTTP status codes. This page lists the ones you will encounter, what they mean and whether a retry is safe.

Every response carries a meaningful HTTP status code. A `2xx` means the request succeeded; anything else signals a problem your client should handle explicitly. Error bodies, when present, are JSON with a `message` field describing the failure.

## Status codes

### `200 OK`

The request succeeded and the body carries the resource.

### `201 Created` / `202 Accepted`

Write endpoints return `201` for direct creates and `202` for batched writes that are accepted for asynchronous processing. Batched writes return a per-item outcome — inspect it before assuming the whole batch landed.

### `204 No Content`

The request succeeded and there is no body to return. Used for deletes and idempotent no-ops.

### `400 Bad Request`

The request body or query string is malformed or has the wrong shape. Not retryable — fix the payload first.

```json
{ "message": "Invalid query filter" }
```

### `401 Unauthorized`

The token is missing, revoked or malformed. Not retryable with the same token — check the [Authentication](/product-api/authentication) guide.

### `403 Forbidden`

The token is valid but lacks the scope required for this endpoint, or the privacy level is insufficient to return the requested fields. Not retryable as-is — mint a token with the right scope, or upgrade the data privilege level. See [scopes in the Guide](/product-api/guide#tokens-and-scopes).

### `404 Not Found`

The `project`, resource id, user id, phone, email or audience id in the URL does not exist or is not visible to the current token.

### `422 Unprocessable Entity`

Validation failed. For batched writes, every item in the batch failed — the body lists per-item errors. Not retryable as-is — fix the items and resubmit.

### `429 Too Many Requests`

You hit the per-endpoint rate-limit window. Retry after `X-RateLimit-Reset`. See [Rate limits](/product-api/rate-limits).

### `500 Internal Server Error`

Something broke on our side. Retry with exponential backoff; if the failure persists, contact support with the request id.

## Retry policy

> **Tip**: Retry `429` and `5xx` with exponential backoff, starting at 1 s and capping at a minute or so. Everything in the `4xx` range other than `429` means the request itself is wrong — retrying will not help.

## What's next

- **[Rate limits](/product-api/rate-limits)** — the `X-RateLimit-*` headers and plan ceilings.
- **[API Reference](/product-api/reference)** — per-endpoint responses and schemas.