Errors

Error response format and common HTTP status codes.

Error Response Shape

All error responses follow a consistent JSON structure with a human-readable message and a machine-readable code.

{
  "error": {
    "message": "Human-readable error message",
    "code": "machine_readable_code"
  }
}

HTTP Status Codes

HTTP Status	Code	Meaning
400	`validation_error`	Invalid request body or parameters
401	`unauthorized`	Missing or invalid API key
402	`payment_required`	Payment required
402	`insufficient_credits`	Not enough credits to complete the request
403	`forbidden`	Forbidden (e.g., Instagram publish permission not granted)
404	`not_found`	Resource not found or API not enabled for account
429	`rate_limit_exceeded`	Too many requests
500	`internal_server_error`	Internal server error

The code field is always present in error responses. A 400 from request validation uses validation_error; other 400 errors use bad_request. A 402 uses insufficient_credits when the error message mentions insufficient credits, and payment_required otherwise.

Example

400 Bad Request

{
  "error": {
    "message": "'model' is required",
    "code": "validation_error"
  }
}