Error Handling

All API errors are returned as JSON with a consistent structure.

Error Response Format

{
  "error": "error_type",
  "message": "Human-readable description of what went wrong",
  "requestId": "req_01H..."
}

Some endpoints include additional detail:

{
  "error": "Invalid prompt data",
  "details": [
    { "path": ["temperature"], "message": "Number must be less than or equal to 2" }
  ]
}

HTTP Status Codes

Status	Meaning	When It Occurs
400	Bad Request	Invalid payload, missing required fields, validation failure
401	Unauthorized	Missing or invalid API key, expired session
403	Forbidden	Key scope insufficient (e.g., read-only key attempting write)
404	Not Found	Resource does not exist or is not accessible
405	Method Not Allowed	HTTP method not supported on this endpoint
409	Conflict	Duplicate resource (e.g., prompt with identical content hash)
429	Too Many Requests	Rate limit exceeded - see Rate Limits
500	Internal Server Error	Unexpected server error - retry with backoff

Validation Errors (400)

When creating or updating resources, validation rules apply:

Prompt Validation

Field	Rule
name	Required, 1-100 characters
userPrompt	Required, minimum 1 character
temperature	Optional, range 0.0 - 2.0 (default: 0.7)
maxTokens	Optional, range 1 - 8000 (default: 1000)
visibility	Optional, one of: PRIVATE, SHARED, PUBLIC

Webhook Validation

Field	Rule
name	Required
url	Required, must be a valid HTTPS URL
events	Required, array of event type strings
secret	Optional, minimum 16 characters if provided

Retry Strategy

async function apiCallWithRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fn();

    if (response.ok) return response;

    // Don't retry client errors (except 429)
    if (response.status >= 400 && response.status < 500 && response.status !== 429) {
      throw new Error(`Client error: ${response.status}`);
    }

    // Retry 429 and 5xx with exponential backoff
    if (attempt < maxRetries) {
      const retryAfter = response.headers.get('Retry-After');
      const delay = retryAfter
        ? parseInt(retryAfter) * 1000
        : Math.min(1000 * Math.pow(2, attempt), 30000);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Max retries exceeded');
}

Troubleshooting Tips

• Always log the requestId from error responses for support inquiries.
• For 401 errors, verify your API key is correctly formatted with the Bearer prefix.
• For 500 errors, retry with exponential backoff. If persistent, check the Status Page.
• For validation errors, check the details array for field-specific messages.

Related Docs

• Rate Limits
• Authentication