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 429 from these endpoints means your monthly AI allowance is exhausted (not that you are sending requests too quickly), and a 403 means your plan does not currently include the feature.

AI Action Allowance Exhausted (429)

Metered AI endpoints (for example voice transcription) draw down a monthly allowance of AI actions. When the allowance is used up, the endpoint returns 429 with code rate_limited and a details object identifying the exhausted feature along with the limit and remaining counts. Unlike a transient rate limit, retrying will not succeed until the allowance resets at the start of the next billing period (or you upgrade your plan).

HTTP/1.1 429 Too Many Requests

{
  "error": {
    "code": "rate_limited",
    "message": "Monthly AI action allowance reached",
    "details": {
      "feature": "ai_actions",
      "limit": 500,
      "remaining": 0
    }
  }
}

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
• 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();
}