Every error tells you what to do next.

The request-time error shape

HTTP/1.1 403 Forbidden
{
  "error":      "MODEL_NOT_ALLOWED",
  "message":    "Your account is not granted access to \"video-cinematic-4k\".",
  "next":       "Call GET /api/v1/models to see allowed slugs, or contact support to request access.",
  "model":      "video-cinematic-4k",
  "request_id": "req_abc123xyz"
}

Always pass request_id when you write to support — it lets us pull up your exact log line in seconds instead of digging through traces. Every response, success or error, carries one (also echoed on the X-Request-Id response header).

Error codes

Auth · 401

Access & billing · 402 / 403

Content & request · 400

Not found · 404

Validation & idempotency · 409 / 422

Rate & concurrency · 429

Server & availability · 500 / 503

Generation failures (async)

POST /api/v1/generate returns 202 the moment a job is accepted — before it has actually rendered. If something goes wrong afterthat (the provider is at capacity, the model rejects the request, a post-render safety check fails), you won't see it as a non-2xx response. You'll see it on the next poll of GET /api/v1/generations/:id, which stays 200 OK with status: "failed" and an error object of its own:

HTTP/1.1 200 OK
{
  "generation_id": "5b91a581-ee19-4f86-9fea-bd29471d69d5",
  "status":        "failed",
  "model":         "grok-imagine-image-quality",
  "output_url":    null,
  "output_urls":   null,
  "credits_used":  0,
  "duration_ms":   3180,
  "created_at":    "2026-05-10T12:34:56Z",
  "completed_at":  "2026-05-10T12:35:00Z",
  "request_id":    "req_9f2c7a1b3d8e",
  "error": {
    "code":      "model_unavailable",
    "message":   "This model is temporarily unavailable. Please try another model — your credits have been refunded.",
    "retryable": true
  }
}

This error.code is a different, lowercase set — model_unavailable, rate_limited, content_blocked, upstream_detail, unknown, and others — not the uppercase codes tabled above. Don't guess whether to resubmit: read error.retryable. true means the identical body has a real chance of succeeding on a second try (capacity, a transient hiccup); falsemeans something about the request itself won't change on a retry (a blocked prompt, an unsupported setting) — resubmitting as-is just burns another charge for the same result.

Recommended patterns

async function generateWithRetry(payload: any, idempotencyKey: string, attempt = 0): Promise<any> {
  const res = await fetch('https://getvivix.com/api/v1/generate', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.VIVIX_KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': idempotencyKey,
    },
    body: JSON.stringify(payload),
  })
  if (res.ok) return res.json()   // 202 — job accepted, poll /generations/:id next

  const body = await res.json()

  // Permanent failures — don't retry as-is.
  if ([400, 401, 402, 403, 404, 422].includes(res.status)) {
    throw new ApiError(body)
  }

  // Idempotency race — the original is still being enqueued. Short wait, same key.
  if (res.status === 409) {
    await sleep(3000)
    return generateWithRetry(payload, idempotencyKey, attempt + 1)
  }

  // Rate-limited — wait the server's recommended duration, same key.
  if (res.status === 429) {
    const retryAfter = Number(res.headers.get('Retry-After') ?? '5')
    await sleep(retryAfter * 1000)
    return generateWithRetry(payload, idempotencyKey, attempt + 1)
  }

  // Server-side hiccup — exponential backoff up to 5 attempts, same key.
  if (res.status >= 500 && attempt < 5) {
    await sleep(Math.min(30_000, 1000 * 2 ** attempt))
    return generateWithRetry(payload, idempotencyKey, attempt + 1)
  }

  throw new ApiError(body)
}

Where to next

• Authentication — how to keep keys safe
• POST /api/v1/generate — the request body every code above responds to
• GET /api/v1/generations/:id — full response shapes, including async failures
• Endpoint reference — every URL, every payload