Error Codes

Error Response Format

All errors follow a consistent structure:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable error description",
    "details": {
      // Additional context (optional)
    }
  }
}

HTTP Status Codes

Error Codes

AI Allowance & Feature Access

A handful of AI-powered endpoints enforce account-level limits that are distinct from the per-key and per-IP rate limits described above. A 402 from these endpoints means your organisation's monthly AI actions are used up (not that you are sending requests too quickly), and a 403 means your plan does not currently include the feature.

AI actions used up (402)

Metered AI endpoints (for example POST /api/v1/questions/check) draw down a monthly allowance of AI actions, and any extra AI action balance the organisation holds is used after it. When both are spent, the endpoint returns 402 with code ai_limit_reached and a details object: limit (the monthly allowance), remaining (what is left, extra balance included), packBalance (the extra balance), resetsAt (when the allowance next resets), offer (what the organisation can do about it: buy_pack when it can buy an AI action pack, upgrade when it cannot but a higher plan exists, and none when there is no plan above its own) and, when known, required (what this call needed). Unlike a rate limit, retrying will not succeed until the allowance resets on resetsAt or the organisation has more AI actions. On a paid plan an owner or admin can buy an AI action pack on the billing page when the offer is buy_pack.

HTTP/1.1 402 Payment Required

{
  "error": {
    "code": "ai_limit_reached",
    "message": "Monthly AI action allowance reached",
    "details": {
      "feature": "ai_actions",
      "limit": 1000,
      "remaining": 0,
      "packBalance": 0,
      "resetsAt": "2026-11-14T00:00:00.000Z",
      "offer": "upgrade",
      "required": 1
    }
  }
}

Changed in October 2026. This refusal used to carry code quota_exceeded. It is now ai_limit_reached on every endpoint, with the same 402 status. quota_exceeded stays in the published list of codes so generated clients keep compiling, but no endpoint returns it: a client that branches on it should branch on ai_limit_reached. Two fields also changed meaning: details.remaining now includes any extra AI action balance, and details.required is in AI actions (the call's weight times its model calls), not model calls.

Feature Not Available (403)

When your plan does not include a requested AI feature (for example voice input), the endpoint returns 403 with code forbidden and the message "This feature is not currently available". This is an entitlement check, not a rate limit — upgrade your plan or enable the feature to gain access.

HTTP/1.1 403 Forbidden

{
  "error": {
    "code": "forbidden",
    "message": "This feature is not currently available"
  }
}

Common Errors

Invalid API Key

HTTP/1.1 401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Missing Scope

HTTP/1.1 403 Forbidden

{
  "error": {
    "code": "invalid_scope",
    "message": "API key missing required scope: questions:write"
  }
}

Validation Error

HTTP/1.1 400 Bad Request

{
  "error": {
    "code": "invalid_request",
    "message": "Validation failed",
    "details": {
      "errors": {
        "title": ["String must contain at least 1 character(s)"],
        "type": ["Invalid enum value"]
      }
    }
  }
}

Cannot Modify Live Survey

HTTP/1.1 400 Bad Request

{
  "error": {
    "code": "invalid_request",
    "message": "Cannot modify questions on a live survey. Pause it first."
  }
}

Error Handling Best Practices

• Check the error code - Use the code field for programmatic error handling
• Log the full response - Include the details field for debugging
• Implement retry logic - For 429 and 500 errors, use exponential backoff. A 402 is not retried: it clears only when the allowance resets.
• Handle validation errors - Display field-specific errors from details.errors

Example Error Handler

async function apiRequest(url, options) {
  const response = await fetch(url, options);

  if (!response.ok) {
    const error = await response.json();

    switch (error.error.code) {
      case 'unauthorized':
        throw new Error('Invalid API key');
      case 'rate_limited':
        // Implement exponential backoff
        await sleep(1000);
        return apiRequest(url, options);
      case 'invalid_request':
        // Handle validation errors
        console.log('Validation errors:', error.error.details?.errors);
        throw new Error(error.error.message);
      default:
        throw new Error(error.error.message);
    }
  }

  return response.json();
}