Documentation

Errors & Troubleshooting

Understanding V2 error codes, their meanings, and how to resolve them.

Error Response Format

All V2 API errors return a consistent JSON structure:

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_field",
    "message": "The 'messages' field is required",
    "param": "messages",
    "request_id": "req-7f65ab21d1"
  }
}

Field	Description
type	Category of error (authentication_error, rate_limit_error, server_error, etc.)
code	Specific error code for programmatic handling
message	Human-readable error description
param	The parameter that caused the error (if applicable)
request_id	Unique ID for support requests

HTTP Status Codes

Code	Type	Example Code	Description	Resolution
400	invalid_request_error	missing_field	Invalid request body or parameters	Check required fields (messages, model)
401	authentication_error	invalid_api_key	Missing or invalid API key	Check x-api-key header
403	forbidden_error	key_revoked	API key revoked or insufficient permissions	Generate new key in console
404	not_found_error	context_not_found	Resource not found or context expired	Verify context_id or model name
409	conflict_error	duplicate_id	Duplicate external_id in same context	Use unique IDs per message
413	invalid_request_error	payload_too_large	Request body exceeds size limit	Reduce message size or split batch
422	invalid_request_error	invalid_role	Invalid value for a field	Use valid roles: user, assistant, system
429	rate_limit_error	too_many_requests	Rate limit exceeded	Retry with exponential backoff
500	server_error	internal	Unexpected server error	Retry; contact support if persistent
503	server_error	service_unavailable	Service temporarily unavailable	Check status page, retry later

Common Issues & Solutions

Authentication Failures (401)

Verify API key is correctly set in x-api-key header
Ensure key format is correct: kaiko_live_xxx (production) or kaiko_test_xxx (staging)
Check if key has been revoked in the console

Rate Limiting (429)

Implement exponential backoff with jitter
Check Retry-After header for wait time
Monitor X-RateLimit-Remaining header
Use batch analysis for multiple texts

Context Not Found (404)

Context IDs expire after 24 hours by default
Verify the context_id was created successfully
Check for typos in the context_id path

Invalid Model (400/404)

V2 emotion model: emotion-v2
LLM models: gpt-4, gpt-4-turbo, gpt-3.5-turbo, claude-3-*, xai-grok
Check model name spelling

Timeout Errors

Default timeout is 30 seconds for non-streaming requests
Use stream: true for long responses
Reduce message history length if hitting context limits

Retry Strategy

Use exponential backoff with jitter for transient errors (429, 500, 503):

async function callWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      // Retry on rate limit or server errors
      if (error.status === 429 || error.status >= 500) {
        const delay = Math.pow(2, i) * 1000 + Math.random() * 200;
        console.log(`Retry ${i + 1}/${maxRetries} after ${delay}ms`);
        await new Promise(r => setTimeout(r, delay));
        continue;
      }
      throw error; // Don't retry client errors (4xx except 429)
    }
  }
  throw new Error('Max retries exceeded');
}

Debugging Checklist

1.Check API key is set correctly in x-api-key header
2.Validate JSON payload (run through a linter)
3.Confirm endpoint path matches V2 format (/v2/...)
4.Check rate limit headers in response
5.Log request_id for support requests

Getting Help

Status Page: status.kaikostudios.xyz - Check for outages
Community: Discord / Forum for community support
Direct Support: support@kaikostudios.xyz - Include request_id and timestamp

Next: see Rate Limits for quota details, or Changelog for recent updates.