DocsAPI reference

API errors

HTTP status codes and the JSON error envelope returned by every failure.

Every error response uses a stable JSON envelope:

{
  "error": "plan_required",
  "required": "pro",
  "message": "The synthetic data API is available on Pro and above."
}

The error field is a stable machine-readable code; message is human-friendly and may change wording across releases. Some codes include extra fields (required, used, limit, supported, min, max, got) — the per-endpoint pages list which.

Status code catalog

HTTP	`error`	When
`400`	`invalid_count`	Data API: `count` is not an integer 1–100.
`400`	`invalid_seed`	Avatar API: empty or > 128 chars.
`400`	`invalid_style`	Avatar API: unknown style. Response includes `supported`.
`401`	`unauthorized`	Missing `Authorization` header on the Data API.
`402`	`quota_exceeded`	Data API: plan's monthly quota is used up. Response includes `used` and `limit`.
`403`	`pat_required`	Data API: token isn't an `sk_live_*` PAT.
`403`	`plan_required`	Data API: org is on Free. Response includes `required: "pro"`.
`404`	`unknown_dataset`	Data API: path segment isn't a supported dataset. Response includes `supported`.
`404`	`not_found`	Data API single-item endpoint with no matching id.
`405`	`method_not_allowed`	Non-`GET` method.
`500`	`internal`	Our fault. Please report.
`503`	`service_unavailable`	Brief outage; retry with backoff.

PreviousAvatar API Next FAQ