Errors

The API uses standard HTTP status codes and returns detailed error information.

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "avatar_id is required",
    "details": {
      "field": "avatar_id",
      "reason": "missing"
    }
  }
}

HTTP Status Codes

Code	Description
`200`	Success
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource does not exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error
`503`	Service Unavailable

Error Codes

Authentication Errors

Code	HTTP	Description
`invalid_api_key`	401	API key is invalid or revoked
`missing_api_key`	401	No API key provided
`expired_api_key`	401	API key has expired

Request Errors

Code	HTTP	Description
`invalid_request`	400	Request body is malformed
`missing_parameter`	400	Required parameter is missing
`invalid_parameter`	400	Parameter value is invalid

Resource Errors

Code	HTTP	Description
`conversation_not_found`	404	Conversation does not exist
`avatar_not_found`	404	Avatar does not exist
`message_not_found`	404	Message does not exist

Rate Limit Errors

Code	HTTP	Description
`rate_limit_exceeded`	429	Too many requests
`quota_exceeded`	429	Monthly quota exceeded

Provider Errors

Code	HTTP	Description
`ai_provider_error`	503	AI provider unavailable
`tts_provider_error`	503	TTS provider unavailable

Handling Errors

Always implement retry logic with exponential backoff for 5xx errors.

JavaScript Example

async function sendMessage(conversationId: string, content: string) {
  const maxRetries = 3;
 
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(
        `https://api.avatarium.ai/v1/conversations/${conversationId}/messages`,
        {
          method: 'POST',
          headers: {
            'Authorization': `Bearer ${API_KEY}`,
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ content }),
        }
      );
 
      if (response.ok) {
        return response.json();
      }
 
      const error = await response.json();
 
      // Don't retry client errors
      if (response.status < 500) {
        throw new Error(error.error.message);
      }
 
      // Retry server errors with backoff
      await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 1000));
    } catch (e) {
      if (attempt === maxRetries - 1) throw e;
    }
  }
}

Avatars Overview