Printago API

Errors

How the API reports failures, and what each status code means.

Use the Status Code

Every failure has a 4xx or 5xx HTTP status. Branch on the status code; the body explains what went wrong but its exact shape varies (below), and message text is meant for humans and may change.

Error Body

Most errors return a JSON object with the status and a message. Some also include an error field with the status name:

404 Not Found 
{
  "statusCode": 404,
  "message": "Part [clx1abc2def3ghi4jkl5mno6] not found",
  "error": "Not Found"
}
401 Unauthorized 
{
  "statusCode": 401,
  "message": "Unauthorized"
}

Validation Errors

Request bodies and path parameters (and the query strings of some endpoints) are type-checked against the schemas in this reference before your request is handled. A body that does not match returns 400 with a list of problems instead of a statusCode field. Each entry names the offending location ($input is the body or query object), the type that was expected, and the value that was sent:

400 Bad Request — request body 
{
  "errors": [
    {
      "path": "$input.fileUris",
      "expected": "Array<string> & MinItems<1>",
      "value": []
    }
  ],
  "message": "Request body data is not following the promised type."
}

Type-checked query strings fail the same way with the message Request query data is not following the promised type. An invalid path parameter (for example an ID in the wrong format) reports a single problem:

400 Bad Request — path parameter 
{
  "path": "$input",
  "reason": "Error on …: invalid type on $input, expect to be string & Pattern<\"^[a-z0-9]{24}$\">",
  "expected": "string & Pattern<\"^[a-z0-9]{24}$\">",
  "value": "not-an-id",
  "message": "Invalid URL parameter value on \"id\"."
}

Unknown properties in a request body are dropped rather than rejected, so a misspelled optional field is silently ignored. Check the field names against this reference.

Status Codes

400 Bad Request
The request failed validation (above), a filter, sort, fields, include or limit value was invalid (see Querying Data), or the request breaks a business rule — the message says which.
401 Unauthorized
The API key is missing, invalid or revoked; the x-printago-storeid header is missing or doesn't match the key; or the request came from an IP address outside the key's allowlist. See Authentication.
403 Forbidden
The key is valid but lacks a permission the endpoint requires (message Insufficient permissions; each endpoint lists what it requires), or the store's plan doesn't include the feature (message This feature requires the '…' entitlement).
404 Not Found
No record with that ID exists in your store, or the path doesn't exist. Records in other stores are never visible, so they also return 404.
409 Conflict
The request clashes with current state: a name that must be unique is already taken, an integration is already connected, or a record changed underneath you. Re-read the record before trying again.
413 Payload Too Large
JSON request bodies are limited to 5 MB. Upload files through signed URLs rather than in a request body.
429 Too Many Requests
A rate limit was hit. These responses come from Printago's edge rather than the API, so the body is not the JSON shape above and there is no Retry-After header. Back off exponentially. See rate limits.
500, 502, 503
Something failed on Printago's side (a 500 body is {"statusCode": 500, "message": "Internal server error"}). Retry with backoff — but for writes, see Retry Safely first, because the change may already have been applied.