Skip to main content

​
The error envelope

Every error response has the same JSON shape: 
{
  "errorCode": "PASS_NOT_FOUND",
  "message": "Pass abc123 not found",
  "correlationId": "01HF8Q2E7R9T4V6X8Z0B2D4F6H"
}
  • errorCode — a stable enum value. Branch your code on this, never on message. Codes are never repurposed; changed semantics always get a new code.
  • message — human-readable detail, safe to log and to show to operators.
  • correlationId — identifies this request across Passlet’s systems. Include it when you contact support about a failed request.
Validation failures (VALIDATION_ERROR) additionally include fieldErrors pinpointing the offending fields.

​
Common error codes

HTTPCodesNotes
400VALIDATION_ERROR, INVALID_INPUT, MISSING_REQUIRED_FIELD, INVALID_FORMATMalformed request or filter grammar violation
401UNAUTHORIZED, TOKEN_EXPIRED, TOKEN_INVALIDMissing or bad access token
403FORBIDDENToken valid but lacks the required scope
404NOT_FOUND, PASS_NOT_FOUND, TEMPLATE_NOT_FOUND, WEBHOOK_NOT_FOUNDResource doesn’t exist in your workspace
409CONFLICT, VERSION_CONFLICT, DUPLICATE_PASS, IDEMPOTENCY_CONFLICT, TEMPLATE_VERSION_NOT_NEWER, SCAN_REVERSAL_WINDOW_EXPIREDState conflicts — e.g. re-using an externalPassId with different data
409PASS_ALREADY_ISSUED, PASS_ALREADY_VOIDED, PASS_NOT_ISSUEDLifecycle-state conflicts
429RATE_LIMITEDSlow down and retry with backoff
5xxINTERNAL_ERROR, PROVIDER_UNAVAILABLERetry with backoff; report persistent failures with the correlationId
Endpoint pages list the specific statuses each operation can return.

​
Retry guidance

  • 4xx (except 429) — don’t retry unchanged; fix the request.
  • 429 / 5xx — retry with exponential backoff and jitter.
  • Batch endpoints report per-item outcomes — a failed item never aborts the whole batch, so check the per-item results rather than the HTTP status alone.