API Error Codes

Below is a comprehensive list of all possible error codes you might encounter when using the Poof API. Each error includes a description, HTTP status code, and a link to detailed documentation about how to handle it.

Error Reference Table

Error Code	Description	HTTP Status
authentication_error	`x-api-key` header missing or not recognised	401
permission_denied	The endpoint or feature is not included in your current plan, or the key is not permitted	403
payment_required	Your plan’s monthly credits are used up, or the credits left do not cover this video	402
rate_limit_exceeded	Per-plan requests-per-minute limit or the global per-IP limit hit	429
validation_error	Bad parameter value or non-multipart body	400
missing_image	No `file` or `url` input in the request	400
image_too_large	Image exceeds 20 MB	400 (413 when rejected by the processing service)
invalid_image	File could not be decoded as JPEG, PNG, WebP or a still GIF	422
processing_failed	The model or encoder failed on this image	500
upstream_error	Processing service unreachable, temporarily unavailable, or timed out	502 / 503 / 504
internal_server_error	Unexpected server error	500
`not_found`	Unknown path	404
video_too_large	Video exceeds 100 MB (`file` upload) or 500 MB (`url`)	413
video_too_long	Video is longer than 5 minutes	400
invalid_video	File could not be decoded as a video	422
job_not_found	Unknown job ID, or the job has expired	404

image_too_large is normally returned as 400 by the API gateway. If an oversized upload reaches the processing service, it is rejected there with 413. Handle both statuses the same way.upstream_error uses 502 (unreachable), 503 (temporarily unavailable) or 504 (timed out). All three are safe to retry with backoff.

Error Response Format

All errors return a flat JSON body:

{
  "code": "validation_error",
  "message": "Invalid value for 'format': expected one of png, jpg, webp.",
  "details": {
    "format": [
      "must be one of: png, jpg, webp"
    ]
  },
  "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
  "doc_url": "https://docs.poof.bg/errors/validation-error"
}

Field	Description
`code`	Machine-readable error code from the table above
`message`	Human-readable description
`request_id`	Unique request ID (also sent as the `X-Request-ID` response header)
`doc_url`	Link to the documentation page for this error
`details`	Optional. For `validation_error` an object mapping field names to messages; otherwise a string or omitted

Every error response also carries an X-Request-ID header equal to request_id. Failed requests are never billed. Video jobs are charged when they are accepted; if a job later fails, its credits are refunded automatically and the reason is reported in the job’s error field (see Get Job). The request_id is useful for support — include it when contacting support@poof.bg about an issue.

Getting Started

Video guides

API Reference

API Error Codes

Error Reference Table

Error Response Format

​Error Reference Table

​Error Response Format

Error Reference Table

Error Response Format