Errors

Error Format

All errors return a consistent JSON envelope:

{
  "statusCode": 400,
  "message": "limit must not be greater than 100",
  "error": "Bad Request"
}

The message field is always a human-readable string (or array of strings for validation errors). The error field is the HTTP status text.

Code	When returned
`200`	Successful GET / action that returns a body
`201`	Resource created (POST)
`202`	Reddit read accepted as an async job. The body is `{ "jobId", "status": "queued" }`; poll `GET /v1/reddit/jobs/{id}` for the result
`204`	Successful DELETE or action with no response body

Code	Meaning
`400`	Bad Request — invalid query params or request body (validation failure)
`401`	Missing or invalid `x-api-key` header
`402`	Plan limit reached (e.g. the tracked-prompt limit on `POST /v1/aeo/prompts`)
`404`	Resource not found, or it belongs to a different organisation
`429`	Rate limit exceeded, or the monthly API credit pool or overage spending cap is used up. Back off and retry, or raise the cap
`500`	Server error — retry with exponential backoff
`503`	Only inside a failed Reddit job (`error.status`): ReddGrow's scraper was unavailable. The credits are refunded; retry later

401 vs 403: The API returns 401 for all authentication failures including an expired or revoked key. 403 is reserved for cases where the key is valid but the organisation lacks the required subscription.
404 scoping: Resources are always scoped to your organisation. A valid ID that belongs to another org returns 404, not 403.
429 headers: When rate-limited the response includes Retry-After (seconds) and X-RateLimit-Reset (Unix timestamp) headers.
Reddit job errors: a finished Reddit job that failed reports error: { status, message }. 403, 404 and 429 are Reddit's own answer (you pay for the pages fetched); 503 is ours and is refunded in full.