Errors

Understanding error responses and how to handle them in your application.

Error Response Format

All API errors follow a consistent JSON format:

Error Responsejson
{
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "details": {
    // Additional context (optional)
  }
}

HTTP Status Codes

StatusMeaningWhen It Happens
200OKRequest succeeded
201CreatedResource created successfully
400Bad RequestInvalid parameters or malformed request
401UnauthorizedMissing or invalid authentication
402Payment RequiredInsufficient credits
403ForbiddenAPI key lacks required scope
404Not FoundResource doesn't exist
429Too Many RequestsRate limit exceeded
500Internal ErrorSomething went wrong on our end

Error Codes

Authentication Errors (401)

CodeDescription
MISSING_AUTHNo Authorization header provided
INVALID_FORMATAPI key format is invalid
KEY_NOT_FOUNDAPI key doesn't exist
KEY_REVOKEDAPI key was revoked
KEY_EXPIREDAPI key has expired

Validation Errors (400)

CodeDescription
INVALID_INPUTMissing or invalid request parameters
INVALID_FILE_TYPEUploaded file type not allowed
FILE_TOO_LARGEFile exceeds size limit
INVALID_URLProvided URL is invalid or inaccessible

Resource Errors (402, 403, 404)

CodeDescription
INSUFFICIENT_CREDITSNot enough credits for this operation
INSUFFICIENT_SCOPEAPI key lacks required permission
NOT_FOUNDRequested resource doesn't exist
MODEL_NOT_FOUNDSpecified model doesn't exist
JOB_NOT_FOUNDJob ID doesn't exist

Error Examples

Insufficient Credits

{
  "error": "Insufficient credits",
  "creditsRequired": 15,
  "creditsRemaining": 5
}

Rate Limit Exceeded

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 30,
  "limits": {
    "type": "minute",
    "limit": 30,
    "used": 31
  }
}

Validation Error

{
  "error": "Missing required field: prompt (string)"
}

Automatic Refunds

If an error occurs after credits have been deducted, Vydra automatically refunds your credits. This includes:

  • AI model generation failures
  • Processing timeouts (30 minutes)
  • System errors during job execution
  • User-cancelled jobs

100% Automatic

Refunds are processed automatically and instantly. No action required on your part. You'll see the refund reflected in your credit balance immediately.
Error Response with Refundjson
{
  "error": "Failed to generate image",
  "refund": {
    "applied": true,
    "creditsRefunded": 5
  }
}

Error Handling Best Practices

JavaScript Error Handlingjavascript
async function callVydraAPI(endpoint, options) {
  const response = await fetch(`https://vydra.ai/api/v1${endpoint}`, {
    ...options,
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
      ...options?.headers,
    },
  });

  const data = await response.json();

  if (!response.ok) {
    // Handle specific error codes
    switch (response.status) {
      case 401:
        throw new Error('Authentication failed: ' + data.error);
      case 402:
        throw new Error(`Insufficient credits. Need ${data.creditsRequired}, have ${data.creditsRemaining}`);
      case 429:
        // Implement retry with backoff
        const retryAfter = data.retryAfter || 60;
        throw new Error(`Rate limited. Retry after ${retryAfter} seconds`);
      default:
        throw new Error(data.error || 'Unknown error');
    }
  }

  return data;
}

🔄 Implement Retries

For 5xx errors and rate limits, implement exponential backoff retries. Don't retry 4xx errors without fixing the request.

📊 Log Errors

Log the full error response including the code and any details. This helps with debugging and monitoring.

👤 Show User-Friendly Messages

Don't show raw API errors to users. Map error codes to friendly messages like "Please try again later" or "You've run out of credits."