Reference

Errors

Every error is an RFC 9457 problem document with a stable code. Branch on the code, show the detail to people.

Format

Errors answer with Content-Type: application/problem+json. The type is a link to the matching section of this page.

402 Payment Required

{
  "type": "https://rogue.sentryq-va.com/docs/errors#insufficient_credits",
  "title": "Payment Required",
  "status": 402,
  "code": "insufficient_credits",
  "detail": "This request costs 120 credits and the account has 45.",
  "request_id": "req_7c9e2b4f1a3d4c6e8f0a1b2c3d4e5f6a"
}

Validation errors add errors[], one entry per field:

400 Bad Request

{
  "type": "https://rogue.sentryq-va.com/docs/errors#invalid_request",
  "title": "Bad Request",
  "status": 400,
  "code": "invalid_request",
  "detail": "Invalid request: prompt: Required; aspect_ratio: This model supports 1:1, 2:3, 3:2, 9:16 and 16:9.",
  "request_id": "req_0b8d6f4a2c1e3b5d7f9a8c6e4b2d0f1a",
  "errors": [
    {
      "field": "prompt",
      "message": "Required"
    },
    {
      "field": "aspect_ratio",
      "message": "This model supports 1:1, 2:3, 3:2, 9:16 and 16:9."
    }
  ]
}

Field	Meaning
`type`	Link to the documentation of this code.
`title`	The HTTP status text.
`status`	The HTTP status code, repeated for convenience.
`code`	The stable, machine-readable error code. Branch on this.
`detail`	A human-readable explanation, safe to show to end users.
`request_id`	Same as the `X-Request-Id` header. Quote it when you report a problem.
`errors`	Optional list of `{ field, message }` for validation problems.

Retrying safely

Retry only the codes marked below as retryable. Everything else fails the same way until the request or the account changes.
On 429 and 503, wait for the Retry-After header (seconds) before the next attempt.
Always send an Idempotency-Key with POST requests and reuse it on retries, so a request that did reach Rogue is never run or charged twice.

A good default: up to 5 attempts, starting at 1 second and doubling, capped at 30 seconds, and never shorter than Retry-After.

All codes

Code	Status	Retry
`invalid_request`	400	No, fix first
`unauthorized`	401	No, fix first
`insufficient_credits`	402	No, fix first
`forbidden`	403	No, fix first
`budget_exceeded`	403	No, fix first
`tier_required`	403	No, fix first
`connection_expired`	403	No, fix first
`not_found`	404	No, fix first
`conflict`	409	No, fix first
`unprocessable`	422	No, fix first
`moderation_blocked`	422	No, fix first
`account_suspended`	423	No, fix first
`email_not_verified`	423	No, fix first
`rate_limited`	429	Yes, after Retry-After
`queue_full`	429	Yes, after Retry-After
`geo_blocked`	451	No, fix first
`internal_error`	500	Yes, with backoff
`upstream_error`	502	Yes, with backoff
`upstream_unavailable`	503	Yes, after Retry-After

invalid_request

400 Bad Request

The request is malformed or a field is invalid: a missing prompt, an unknown model, an aspect ratio the model does not offer, a query parameter out of range. When specific fields are at fault, errors[] lists each one.

What to do: Correct the request. Sending it again unchanged gives the same answer.

unauthorized

401 Unauthorized

No API key was sent, or the key is malformed, revoked or expired.

What to do: Send Authorization: Bearer rk_live_.... If the key was revoked or expired, create a new one in the console.

insufficient_credits

402 Payment Required

The Rogue account does not have enough credits for this request. Nothing was queued or charged.

What to do: Top up in Rogue Studio. Use POST /v1/estimate to price a request before you send it.

forbidden

403 Forbidden

The key is valid but lacks the scope this route needs, or the action is not allowed for this account.

What to do: Check the scopes on the API keys page and create a key that has the one you need. The scope table lists what each allows.

budget_exceeded

403 Forbidden

The request would take this key over its daily credit budget. Nothing was queued or charged.

What to do: Wait for the budget to reset at 00:00 UTC, or use a key with a larger budget.

tier_required

403 Forbidden

The Rogue plan on this account does not include this model or feature.

What to do: Pick a model your plan includes (GET /v1/models lists only those) or upgrade in Rogue Studio.

connection_expired

403 Forbidden

The Rogue session behind this key has ended and could not be refreshed.

What to do: The key owner signs in to the console again. Keys stay the same and work again immediately.

not_found

404 Not Found

The resource does not exist, or it belongs to another account.

What to do: Check the id. Ids are prefixed by type, for example gen_ for generations and upl_ for uploads.

conflict

409 Conflict

The request clashes with the current state: canceling a generation that was already sent to Rogue, reusing an Idempotency-Key for a different request, or going over the number of keys or webhook endpoints allowed.

What to do: Read the detail, fetch the current state and decide from there.

unprocessable

422 Unprocessable Content

The request was well formed, but Rogue rejected the input, for example a reference that cannot be used with this model or a combination of settings it refuses.

What to do: Read detail and errors[], adjust the input and send it again.

moderation_blocked

422 Unprocessable Content

Rogue's moderation blocked the prompt or a reference image.

What to do: Change the prompt or the media. Retrying the same input is blocked again.

account_suspended

423 Locked

The Rogue account behind this key is suspended.

What to do: Contact Rogue support. The API works again as soon as the account does.

email_not_verified

423 Locked

The Rogue account behind this key has not verified its email address.

What to do: Verify the email in Rogue Studio, then retry.

rate_limited

429 Too Many RequestsRetryable

The key went over its requests per minute, or Rogue is rate limiting the account.

What to do: Wait for the number of seconds in Retry-After, then retry. Spread bursts out and watch X-RateLimit-Remaining.

queue_full

429 Too Many RequestsRetryable

The account has as many generations running on Rogue as its plan allows. Our queue normally absorbs this, so you rarely see it.

What to do: Retry after Retry-After seconds, or let jobs queue and follow them with webhooks.

geo_blocked

451 Unavailable For Legal Reasons

Rogue is not available in this location.

What to do: Nothing to change on the request. The restriction comes from Rogue.

internal_error

500 Internal Server ErrorRetryable

Something failed on our side.

What to do: Retry with backoff and the same Idempotency-Key. If it persists, report the request_id.

upstream_error

502 Bad GatewayRetryable

Rogue answered with an unexpected error.

What to do: Retry with exponential backoff, reusing the same Idempotency-Key for POST requests.

upstream_unavailable

503 Service UnavailableRetryable

Rogue is down for maintenance, overloaded or did not answer in time.

What to do: Retry after Retry-After seconds with the same Idempotency-Key: if the first attempt did reach Rogue, you get that result instead of a second charge.