API reference

Errors

Every Dhanu API error uses one envelope with a machine-readable code. Here is the full list and what to do about each.

Every failed request returns the same shape:

{
  "error": {
    "code": "invalid_api_key",
    "message": "Missing or unknown API key"
  }
}

Branch on code, not on message — messages are written for humans and may be reworded.

Authentication and access

Code	Status	What happened	What to do
`invalid_api_key`	401	Missing or unknown bearer key	Check the `Authorization` header
`api_key_revoked`	401	The key was revoked	Create a new key
`developer_access_revoked`	403	The key’s creator lost developer access in the workspace	Restore their access, or issue a new key
`api_key_project_scope`	403	The key covers no active projects, or `projectId` is out of scope	Fix the key’s project scope

Request problems

Code	Status	What happened
`project_id_required`	422	A multi-project key called without `projectId`
`invalid_generation_prompt`	422	Prompt was empty or longer than 2000 characters
`invalid_image_aspect_ratio`	422	Aspect ratio outside the five supported values

Billing and limits

Code	Status	What happened	What to do
`insufficient_credits`	402	Workspace credit balance is zero or below	Top up in Settings → Billing
`rate_limited`	429	Too many requests for this workspace	Back off — see Rate limits

Request IDs

Every response carries a request id, and it is included in the error envelope. You can supply your own with the x-request-id header — it must match [A-Za-z0-9._~-]{8,128}, otherwise Dhanu generates one — and it is echoed back on the response.

Include the request id when you contact support. It is the fastest way for us to find what happened.

Handling errors with the SDK

The SDK throws DhanuError, carrying the same code plus the request id:

import { DhanuError } from "dhanu";

try {
  await dhanu.images.generate({ prompt: "…" });
} catch (err) {
  if (err instanceof DhanuError) {
    console.error(err.code, err.status, err.message, err.requestId);
  }
}

Overview

Authentication