Watermark API
For AI agents Get an API key
Use the API

Errors

View as Markdown

One error shape for every endpoint. Branch on the code, show the message.

Every error has the same shape and an HTTP status that matches its type:

JSON 
{
  "error": {
    "type": "invalid_request",
    "code": "validation_failed",
    "message": "The operations.0.width field must be between 1 and 20000.",
    "param": "operations.0.width",
    "request_id": "1234"
  }
}

Branch on code; show message to people. A validation error also lists every field under errors.

Status Type Codes
401 authentication missing_api_key, invalid_api_key
402 payment_required insufficient_credits, paid_account_required
403 permission account_suspended
404 not_found request_not_found, not_found
409 conflict request_finished, idempotency_key_reused, idempotency_key_in_use
422 invalid_request validation_failed, url_invalid, url_blocked, url_unresolvable
429 rate_limited rate_limited (wait for Retry-After), concurrency_limited (wait for one of your requests to finish), test_mode_daily_limit
500 server_error server_error: retry; write to support@watermark.ws if it persists

A request that fails while processing

A request that was accepted but could not be processed ends with status failed and an error on the request (and its webhook), not an HTTP error:

Code Meaning
url_blocked, url_invalid, url_unresolvable The source or a watermark image points somewhere the API will not fetch.
source_unreachable The source could not be downloaded (not found, timed out, refused).
source_too_large The source is larger than your tier allows.
unsupported_media The file is not a format the endpoint accepts.
encrypted_document The PDF is password-protected.
processing_failed The file could not be processed.

Failed requests are not charged.