Errors and versioning

Errors

Every error answers the same way: a code your code can rely on, a message for people, the requestId, and the details of that error.

curl -H "Authorization: Bearer $PAPRIKA_KEY" "$PAPRIKA_URL/v1/templates/tpl_0000000000000000"

{ "code": "not-found", "message": "Not found", "requestId": "5522cf61" }

The codes are stable; messages can be reworded. Every code is in the API reference, under each route’s answers. The requestId is also the X-Request-Id header of every answer: when you ask for help, give it, and whoever runs Paprika finds the request in the server’s log.

Status	When	What to do
400 bad-request	The request isn’t what the route takes; the message says what.	Fix the request.
401 unauthorized	No key, or one that isn’t valid.	See Authentication.
403 scope-missing	The key hasn’t the scope the route needs.	Use a key with that scope.
404 not-found	No such template, version, job, output or route.
409	A conflict, such as a filename taken or a resource missing; the code says which.
413 request-too-large	The body is larger than the route takes.
422	The values break the template’s contract (values-invalid, with every problem), or the document has layout errors its policy refuses.	Fix the values or the template.
429 rate-limited	Past your plan’s requests a minute.	Wait the Retry-After header’s seconds.
503 busy	Every renderer is busy.	Wait the Retry-After seconds, or submit a job.
504 render-too-slow	A direct render took too long to wait for.	Submit it as a job.
500 internal-error	A fault of the server’s.	Retry later; if it lasts, report the requestId.

Retry 429, 503 and 500 only, after a pause; anything else answers the same way again. A job or batch submitted with an Idempotency-Key header can be retried safely: the same key gives back the same job.

Versions of the API

Every route is under /v1. Within v1 changes only add: new routes, new optional settings, new fields in answers. So ignore the fields you don’t know, and your integration keeps working. A change that would break one makes /v2, and v1 stays for at least 12 months after it.

A route that is going away is marked deprecated in the API reference, and answers with a Deprecation header and a Sunset header giving the date it stops.

The routes the reference doesn’t list serve the Paprika editor: they can change without notice, so don’t call them.