Reference
Error codes
Every non-2xx response from the /v1/generate, /v1/jobs and /v1/usage endpoints uses the same ErrorResponseV1 shape: { "error": { "code", "message", "requestId", "details"? } }, with the request id also in the X-Request-ID header. A failed job carries error: { code, message } on the job itself. Match on code, not on message, which may change.
| Code | HTTP status | Meaning |
|---|---|---|
| AUTH_MISSING | 401 | No API key was sent. Use Authorization: Bearer <key> or X-API-Key: <key>. |
| AUTH_INVALID | 401 | The API key is unrecognized or revoked, or its account is inactive. |
| SCOPE_INSUFFICIENT | 403 | The key is valid but lacks the scope this endpoint needs (generate, jobs:create, jobs:read or usage:read). |
| QUOTA_EXCEEDED | 429 | Your account reached its monthly word or request allowance. It resets at the start of the next calendar month (UTC); details.periodEnd says when. |
| RATE_LIMITED | 429 | This key exceeded its requests-per-minute or requests-per-day limit. Wait for the Retry-After header (seconds) before retrying. |
| VALIDATION_ERROR | 400 | The body is not valid JSON, is over 256 KB, fails the request schema (see details.issues), or reuses an idempotency key with a different body. |
| PROHIBITED_INPUT | 422 | Content generation was declined for this request. Rephrase the keywords or topic; retrying the same input will not help. |
| JOB_NOT_FOUND | 404 | No job with this jobId exists for your account. |
| CONTENT_QUALITY_FAILED | 422 | Returned only for factualityMode: "verified" requests when nothing could be verified: no targetUrl, or no fact from the page survived verbatim-quote verification. Ordinary quality-gate failures are not errors. The article is returned (200, or a succeeded job) with quality.status "fail" and quality.qa.failingGates. |
| SOURCE_VALIDATION_FAILED | 422 | For a topic that depends on current information, not enough recent (last 7 days), relevant and consistent news coverage was found after 3 retrieval attempts, so no article was written. Try again later or broaden the topic. |
| INTERNAL_ERROR | 500 | An unexpected server error or a temporary generation outage. Retry later, with a new idempotency key if you used one. |
| JOB_FAILED | 200 | Returned on a failed job, not as an HTTP error: the job resource comes back with HTTP 200, status "failed", and error.code JOB_FAILED. error.reason holds the underlying code (for example INTERNAL_ERROR or SOURCE_VALIDATION_FAILED). The job.failed webhook carries the same error object. |
Example: auth missing
401
{
"error": {
"code": "AUTH_MISSING",
"message": "API key is required.",
"requestId": "req_5c6d7e8f90"
}
}Example: auth invalid
401
{
"error": {
"code": "AUTH_INVALID",
"message": "Invalid or revoked API key.",
"requestId": "req_a1b2c3d4e5"
}
}Example: scope insufficient
403
{
"error": {
"code": "SCOPE_INSUFFICIENT",
"message": "This API key does not have permission to access this endpoint.",
"requestId": "req_0a9b8c7d6e"
}
}Example: quota exceeded
429
{
"error": {
"code": "QUOTA_EXCEEDED",
"message": "Monthly word quota exceeded for plan 'growth'. Upgrade your plan or wait for the next billing period.",
"requestId": "req_f6e5d4c3b2",
"details": {
"monthlyWords": 200000,
"consumedWords": 200000,
"monthlyRequests": 5000,
"consumedRequests": 231,
"periodEnd": "2026-10-01T00:00:00.000Z"
}
}
}Example: rate limited
429
{
"error": {
"code": "RATE_LIMITED",
"message": "Too many requests per minute. Please slow down.",
"requestId": "req_11223344aa",
"details": {
"limit": 15,
"remaining": 0,
"resetAt": "2026-09-14T10:21:00.000Z"
}
}
}Example: validation error
An unsupported tone value:
400
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request body.",
"requestId": "req_99887766bb",
"details": {
"issues": [
{
"path": [
"tone"
],
"message": "Invalid option: expected one of \"professional\"|\"friendly\"|\"bold\""
}
]
}
}
}Example: job not found
404
{
"error": {
"code": "JOB_NOT_FOUND",
"message": "No job was found with this ID.",
"requestId": "req_4d5e6f7a8b"
}
}Example: prohibited input
422
{
"error": {
"code": "PROHIBITED_INPUT",
"message": "The request could not be completed because the model declined to generate content for it.",
"requestId": "req_55443322cc"
}
}Example: generation failure
500
{
"error": {
"code": "INTERNAL_ERROR",
"message": "Content generation is temporarily unavailable. Please try again shortly.",
"requestId": "req_33221100dd"
}
}Example: content quality failed
A factualityMode: "verified" request that could not be verified. details.failedCheckCodes lists the blocking check codes. See the content quality pipeline.
422
{
"error": {
"code": "CONTENT_QUALITY_FAILED",
"message": "Generated content did not meet the required quality standard after automatic correction.",
"requestId": "req_77889900ee",
"details": {
"revisionCount": 0,
"overallScore": 0,
"failedCheckCodes": [
"FACTUALITY_UNVERIFIED"
]
}
}
}Content feed endpoints
The content feed endpoints use the same { "error": { "code", "message" } } shape, without a requestId, and their own codes:
| Code | HTTP status | Meaning |
|---|---|---|
| NOT_FOUND | 404 | Unknown token, or unknown item for this token. |
| RULE_NOT_FOUND | 404 | The ?rule= value matches no rule on this token. |
| NOT_RESERVED | 409 | Confirm or reject on an item that is no longer the reserved one. |
| VALIDATION_ERROR | 400 | A reject body that isn’t { "reason": string } (1–1,000 characters) or is over 8 KB. |