Errors

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.

{ "message": "Invalid query filter" }

401 Unauthorized

The token is missing, revoked or malformed. Not retryable with the same token — check the 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.

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.

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

What's next

• Rate limits — the X-RateLimit-* headers and plan ceilings.
• API Reference — per-endpoint responses and schemas.