Pathwize API

Errors

Every error has a type, a human-readable message and, where possible, the field that caused it.

{
  "error": {
    "type": "invalid_request_error",
    "message": "mime must be one of image/jpeg, image/png, image/webp, application/pdf, text/plain, application/json.",
    "param": "items[3].mime"
  }
}

HTTP	type	When
400	`invalid_request_error`	The body or a query parameter is malformed. Fix the request; do not retry as is.
401	`authentication_error`	API key missing, malformed or revoked.
404	`not_found_error`	No task with that ID in your workspace.
409	`idempotency_error`	The Idempotency-Key was reused with a different request body.
429	`rate_limit_error`	Too many requests. Honour the `Retry-After` header (seconds).
500	`api_error`	Something failed on our side. Safe to retry with the same Idempotency-Key.

Rate limits

120 item pushes per minute and 600 reads per minute per key. A push can carry 1,000 items, so the practical ceiling is well above 100,000 items per minute. Bursts above the limit get 429 with Retry-After.

Retries

Retry 429 and 5xx with exponential backoff (1 s, 2 s, 4 s, up to 5 tries).
Always send an Idempotency-Key on pushes so a retry after a timeout cannot double-create.
Do not retry 400, 401 or 404; the request itself needs to change.
Validation problems inside a batch never fail the whole request. Read rejected, fix those items and push them again.