Error Handling

Learn how to handle errors returned by the API.

Error Response Format

When an error occurs, the API returns a JSON response with the following structure:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "A human-readable description of the error"
  }
}
    

Authentication Errors

Error Code	HTTP Status	Description	Solution
`MISSING_API_TOKEN`	401	No API token provided	Include the Authorization header with your token
`INVALID_API_TOKEN`	401	Token is invalid or revoked	Check your token or regenerate a new one
`ACCOUNT_INACTIVE`	403	Account not activated	Complete a payment to activate your account

Balance Errors

Error Code	HTTP Status	Description	Solution
`INSUFFICIENT_BALANCE`	402	Not enough credits	Purchase more credits

Example Response

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "You need 50 credits but only have 25. Please purchase more credits.",
    "required": 50,
    "available": 25
  }
}
    

Request Errors

Error Code	HTTP Status	Description	Solution
`INVALID_PLATFORM`	400	Unsupported platform specified	Use: tiktok, instagram, twitter, x, snapchat, or linkedin
`INVALID_PARAMETERS`	400	Invalid query parameters	Check parameter types and values
`NOT_FOUND`	404	Endpoint doesn't exist	Check the endpoint URL

Rate Limiting

To ensure fair usage, the API implements rate limiting. If you exceed the limits, you'll receive:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please wait before trying again.",
    "retry_after": 60
  }
}
    

The retry_after field indicates how many seconds to wait before making another request.

Server Errors

Error Code	HTTP Status	Description	Solution
`INTERNAL_ERROR`	500	Server-side error occurred	Retry the request; contact support if persistent
`SERVICE_UNAVAILABLE`	503	Service temporarily unavailable	Wait and retry; check status page

Best Practices for Error Handling

1. Always check the success field - Don't assume requests succeed
2. Use the error code - For programmatic error handling
3. Display the message - For user-friendly error messages
4. Implement retry logic - For transient errors (5xx), retry with exponential backoff
5. Monitor your balance - Check remaining_balance in responses