API Errors

Use HTTP status codes to decide whether to fix the request, refresh credentials, or retry later.

Status	Meaning	Typical handling
400	Request payload is invalid.	Fix the request body or options.
401	API key is missing, invalid, or revoked.	Provide a valid token.
403	Token does not have access.	Check account and token permissions.
404	Operation or PDF was not found.	Check the operation ID or idempotency key.
409	Idempotency key conflict or PDF requested before it is available.	Use the same payload for the same key, choose a new key, or wait for completion.
429	Too many integration requests in a short period.	Wait and retry later.
500	Unexpected server error.	Retry later; contact support if it persists.

Running asynchronous responses include Retry-After. Use that value instead of polling aggressively.

Error Response Shape

Most API errors return application/problem+json:

{
  "title": "Request validation failed",
  "status": 400,
  "detail": "The request body is invalid."
}

Use the HTTP status code for automated handling. Use detail for logs and diagnostics, but do not build client logic that depends on exact wording.

Retry Guidance

Retry only when the failure is temporary:

• Retry 429 after waiting.
• Retry 500 and network timeouts with backoff.
• Poll asynchronous Running operations using the Retry-After response header.

Do not automatically retry 400, 401, 403, or 409 without changing the request, token, permissions, or idempotency key usage.