Handling errors from the Swiftia API

The Swiftia API uses standard HTTP status codes to indicate the success or failure of a request. In case of an error, the API returns a JSON object with a consistent format to provide details about the issue.

Error Response Format

{
  "status": 400, // HTTP status code (e.g., 400, 401, 404, 500)
  "message": "Invalid request parameters", // Descriptive error message
  "code": "INVALID_INPUT" // (Optional) A specific error code for programmatic handling
}

Common Error Codes

• 400 Bad Request (INVALID_INPUT): The request parameters are invalid or missing required fields.
• 401 Unauthorized (UNAUTHORIZED): The request is not authorized (missing or invalid API key).
• 403 Forbidden (FORBIDDEN): The request is forbidden due to insufficient permissions, storage, credits, or unverified phone number.
• 404 Not Found (NOT_FOUND): The requested resource (e.g., job, render) was not found.
• 429 Too Many Requests (RATE_LIMIT_EXCEEDED): You have exceeded the rate limit for your API key.
• 500 Internal Server Error (INTERNAL_SERVER_ERROR): An unexpected error occurred on the server. Please try again later.

403 Forbidden Errors

The 403 Forbidden status code is used for several different scenarios:

Storage Limit Exceeded (fullStorage)

When your organization has insufficient storage space to create new jobs:

{
  "error": "fullStorage",
  "message": "Insufficient storage space. Please upgrade your plan or delete some files to create new jobs.",
  "storageInfo": {
    "usedSize": 950,
    "totalSize": 1000,
    "availableSize": 50
  }
}

Resolution: Upgrade your plan or delete existing files to free up storage space.

Phone Verification Required

When phone verification is enabled but your phone number is not verified:

{
  "error": "Phone verification required",
  "message": "Please verify your phone number before creating jobs",
  "phoneNumber": "+1234567890"
}

Resolution: Verify your phone number through the provided verification process.

Insufficient Credits (noEnoughCredit)

When you don't have enough credits to process the requested job:

{
  "error": "noEnoughCredit",
  "message": "Insufficient credits to process this job"
}

Resolution: Add more credits to your account or upgrade your plan.

Example Error Response

{
  "status": 400,
  "message": "The 'youtubeVideoId' parameter is required.",
  "code": "INVALID_INPUT"
}

Handling Errors in Your Code

Always check the HTTP status code of the response before processing the data. If the status code indicates an error (4xx or 5xx), parse the JSON response to understand the specific error.

Example (Python)

import requests

response = requests.get('https://app.swiftia.io/api/jobs/INVALID_JOB_ID')

if response.status_code != 200:
    try:
        error_data = response.json()
        print(f"Error: {error_data['message']} (Code: {error_data.get('code', 'UNKNOWN')})")
    except ValueError:  # JSON decoding error
        print(f"Error: {response.status_code} - {response.text}")
else:
    # Process the successful response
    data = response.json()
    # ...