Error Codes

API error codes and troubleshooting

Error Codes

Reference for all APIXO API error codes and how to handle them.

HTTP Status Codes

Code	Name	Description	Action
`200`	OK	Request successful	Process the response
`400`	Bad Request	Invalid request parameters	Check your request body
`401`	Unauthorized	Missing or invalid API key	Verify your API key
`403`	Forbidden	API key lacks permission	Check key permissions
`404`	Not Found	Resource doesn't exist	Verify model ID or task ID
`429`	Too Many Requests	Rate limit exceeded	Wait and retry with backoff
`500`	Server Error	Internal server error	Retry after a few seconds
`503`	Service Unavailable	Model temporarily unavailable	Try again later

Task Failure Codes

When a task fails, the response includes failCode and failMsg:

{
  "data": {
    "state": "failed",
    "failCode": "CONTENT_VIOLATION",
    "failMsg": "Content violates usage policy"
  }
}

Content Errors

failCode	Description	Solution
`CONTENT_VIOLATION`	Prompt violates content policy	Modify your prompt
`NSFW_DETECTED`	NSFW content detected	Use appropriate content
`PROMPT_TOO_LONG`	Prompt exceeds character limit	Shorten your prompt
`INVALID_PROMPT`	Prompt is empty or malformed	Provide a valid prompt

Image/Media Errors

failCode	Description	Solution
`INVALID_IMAGE_URL`	Cannot access the provided image URL	Use a publicly accessible URL
`IMAGE_TOO_LARGE`	Input image exceeds size limit	Resize to under 10MB
`UNSUPPORTED_FORMAT`	Image format not supported	Use JPEG, PNG, or WebP
`IMAGE_DOWNLOAD_FAILED`	Failed to download reference image	Check URL accessibility

Processing Errors

failCode	Description	Solution
`PROCESSING_TIMEOUT`	Generation took too long	Retry the request
`MODEL_UNAVAILABLE`	Model is temporarily offline	Try again later
`GENERATION_FAILED`	Generic generation failure	Retry with different parameters
`INSUFFICIENT_CREDITS`	Account has no credits	Add credits to your account

Error Response Examples

400 Bad Request

{
  "code": 400,
  "message": "Invalid request",
  "data": {
    "error": "Missing required field: input.prompt"
  }
}

401 Unauthorized

{
  "code": 401,
  "message": "Unauthorized",
  "data": {
    "error": "Invalid or missing API key"
  }
}

429 Rate Limited

{
  "code": 429,
  "message": "Rate limit exceeded",
  "data": {
    "error": "Too many requests",
    "retryAfter": 60
  }
}

Error Handling Best Practices

Retry Strategy

async function apiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || 60;
        await new Promise(r => setTimeout(r, retryAfter * 1000));
        continue;
      }
      
      if (response.status >= 500) {
        await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 1000));
        continue;
      }
      
      return response;
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 1000));
    }
  }
}

Handling Task Failures

async function handleTaskResult(model, taskId, apiKey) {
  const response = await fetch(
    `https://api.apixo.ai/api/v1/statusTask/${model}?taskId=${taskId}`,
    { headers: { 'Authorization': `Bearer ${apiKey}` } }
  );
  
  const { data } = await response.json();
  
  if (data.state === 'failed') {
    switch (data.failCode) {
      case 'CONTENT_VIOLATION':
        console.error('Please modify your prompt');
        break;
      case 'PROCESSING_TIMEOUT':
        console.log('Retrying...');
        // Retry the original request
        break;
      case 'INSUFFICIENT_CREDITS':
        console.error('Please add credits');
        break;
      default:
        console.error(`Error: ${data.failMsg}`);
    }
    return null;
  }
  
  return JSON.parse(data.resultJson).resultUrls;
}

Getting Help

If you encounter persistent errors:

Check the status page for outages
Review your request against the API Reference
Contact support with your taskId for debugging

Error Codes

On this page