Troubleshooting
Diagnose authentication, upload, output and quota failures before retrying. Use the HTTP status, API error code and sanitized request ID together.
Start with the response
Record the method, route template, status, error code and request ID. JSON errors use meta.requestId; binary responses expose the request ID in headers. Remove credentials, sensitive content and file data before sharing a diagnostic.
| Symptom | Check / next action |
|---|---|
| 401 or missing key | Send X-API-Key; check active key, exact header spelling and deployment origin. Never send both key and Bearer. |
| 403 or wrong project | Compare GET /v1/api-key/context projectId with the path; inspect entitlement and usage in the Customer portal. |
| 404 media | Use the returned resource ID, correct project and active resource. A local filename is not a resource ID. |
| Invalid multipart upload | Use file, not files/image; let the HTTP client create the boundary. For image uploads X-Upload-Length is exact file bytes, not total multipart size. |
| Unexpected JSON instead of media | Check status first. PDF multi-page render intentionally returns JSON with base64 pages; an error also returns JSON. |
| Blank image after 304 | Retain cached bytes. 304 has no new body; do not replace the cached image with an empty file. |
PLAN_LIMIT_EXCEEDED | Review limits/entitlements; shrinking or delaying a request may not resolve an exhausted quota. Do not retry indefinitely. |
429 / IMAGE_BUSY / TOOL_BUSY | Reduce concurrency and use bounded backoff only when replay is safe; inspect Retry-After when supplied. |
Timeout after POST | The operation may already have run. Reconcile known IDs/state before replaying a chargeable or persistent operation. |
| Remote image rejected | Review configured source allowlists, every redirect target, TLS, file type and size; private network fetches are blocked. |
PDF selection and file problems
Pages are one-based. Choose one selector: pages=1,3, both rangeStart and rangeEnd, or render-only all=true. Do not combine them. Render defaults to page 1; extract requires an explicit selection.
Encrypted, invalid and oversized PDFs are terminal input errors. Multi-page render data is base64: decode each page once, using its content type. Never treat JSON text or base64 text as raw PNG bytes.
Escalate with useful context
Include your language/runtime, SDK version if used, route, timestamp, status, error code and request ID in account support. Describe expected and actual behavior using a small synthetic reproduction. Never attach your key, session token or private customer media.
The error reference lists API codes; the API reference lists request and response contracts.
Documentation reviewed 2026-10-03 against development backend e298ec7. Verify your deployment’s API origin and limits before integrating.