Errors#

Every JSON response from the ZUKU API uses one shared envelope. Failures carry a stable code, a human-readable message, and, for field validation, a details array. Clients can map these to an ApiFailure(code, message, status) pattern.

Response envelope#

Success#

{
  "success": true,
  "data": { },
  "meta": {
    "request_id": "…",
    "timestamp": "2026-08-22T00:00:00Z",
    "version": "v1"
  }
}

• data: the endpoint-specific payload.
• meta.version: currently always "v1". It's the same API generation as the /api/v1 URL prefix and the X-API-Version header.

Failure#

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Please check your input",
    "details": [
      { "field": "title", "message": "Title must be 1–100 characters" }
    ]
  },
  "meta": {
    "request_id": "…",
    "timestamp": "…",
    "version": "v1"
  }
}

• details is included only when there is field-level validation.
• Simple failures contain only code and message.

Exceptions#

HTTP status codes#

Error codes#

These are the codes the API actually returns. Delegated moderation and analytics modules may return the same codes.

Authentication and permissions#

Validation and request format#

Sign-up and accounts#

Captcha#

Not found#

Media and Jump#

Rate limits#

Infrastructure and other#

A client-side ApiFailure helper may produce INVALID_RESPONSE when the envelope can't be parsed, and HTTP_ERROR for an error with an empty body. These are generated by the client, not returned by the server.

Field errors in details[]#

For VALIDATION_ERROR and similar codes:

"details": [
  { "field": "title", "message": "Title must be 1–100 characters" },
  { "field": "tags", "message": "Up to 10 tags are allowed" }
]

Common field values when creating content are title, description, tags, age_rating and type. Map details to inline field errors. When it's missing, show error.message as a toast or banner.

Response headers#

Rate-limited requests carry headers based on actual measured counts. Success responses describe the default window for that request kind. A 429 describes the window of the condition that actually rejected the request.

For 429 RATE_LIMITED, error.details includes plan, scope, limit, remaining, window_seconds, retry_after_seconds, reset_at and upgrade_available. reset_at is in Unix epoch seconds. If the counter can't be confirmed, the API returns 503 RATE_LIMIT_UNAVAILABLE. Existing MFA, chat and provider limits keep their own error codes and retry guidance.

See Rate limits for the limits and rollout conditions. To tell the old placeholder headers from the new policy, check real responses and GET /api/v1/rate-limits/policy.

Other CORS and API version headers keep their existing contract. Personal limits and 429 responses aren't stored in shared caches.

Handling errors in JavaScript#

class ApiFailure extends Error {
  constructor(
    public code: string,
    message: string,
    public status: number,
    public details?: { field: string; message: string }[],
  ) {
    super(message);
    this.name = 'ApiFailure';
  }
}

async function apiFetch<T>(path: string, init?: RequestInit): Promise<T> {
  const res = await fetch(`/api/v1${path}`, {
    ...init,
    headers: {
      'Content-Type': 'application/json',
      ...(init?.headers ?? {}),
    },
  });

  if (res.status === 204) return undefined as T;

  const envelope = await res.json();
  if (!envelope.success) {
    throw new ApiFailure(
      envelope.error.code,
      envelope.error.message,
      res.status,
      envelope.error.details,
    );
  }
  return envelope.data as T;
}

// Example
try {
  await apiFetch('/contents', { method: 'POST', body: JSON.stringify(payload), headers: {
    Authorization: `Bearer ${token}`,
  }});
} catch (e) {
  if (e instanceof ApiFailure) {
    switch (e.code) {
      case 'UNAUTHORIZED':
        // Prompt the user to sign in
        break;
      case 'VALIDATION_ERROR':
        // Highlight form fields using e.details
        break;
      case 'EMAIL_EXISTS':
      case 'HANDLE_EXISTS':
        // Sign-up form specific message
        break;
      case 'CAPTCHA_FAILED':
        // Retry the captcha
        break;
      case 'DB_UNAVAILABLE':
      case 'INTERNAL_ERROR':
        // Retry later
        break;
      default:
        console.error(e.code, e.message, e.status);
    }
  }
}

CLI troubleshooting#

The zuku CLI reports failures as CODE: message on stderr, or as {"success":false,"error":{...}} with --json. It reports server failures with the HTTP status and a verified API code, and never prints raw remote responses or tokens.

Don't assume every 422 has the same cause. For paid or publishing actions with an unknown outcome, check the state before you run the command again.

Related pages#

• Contents
• Media
• Rate limits
• Changelog: meta.version and X-API-Version