Errors

The API uses normal HTTP status codes with JSON bodies.

#401 Unauthenticated

The bearer token is missing, invalid, or revoked:

{
  "message": "Unauthenticated."
}

Create a token under Settings > API Tokens and send it as Authorization: Bearer YOUR_TOKEN. See Authentication.

#422 Validation failed

The request body did not pass validation. The response has a summary message and a per-field errors map:

{
  "message": "The quality field requires optimize to be true.",
  "errors": {
    "quality": [
      "The quality field requires optimize to be true."
    ]
  }
}

Common causes:

• The base64 input is not a valid image, or the decoded size is over the 15 MiB limit.
• format is the same format the image already has (convert needs a different target; use Optimize instead).
• quality was sent without optimize: true on convert or resize.
• Neither width nor height was sent to resize.

#5xx Server errors

Something went wrong on our side while processing the image. It is safe to retry. Nothing is ever stored halfway, because the API is stateless.