Error Codes

All API errors across Passage Connect and Passage Platform follow a consistent format.

Error response format

Regular errors return a string message:


{
  "error": "Link not found"
}

Validation errors include structured issue details:


{
  "error": "Validation failed",
  "issues": [
    { "path": "webhookUrl", "message": "must be a valid URL" },
    { "path": "expiresIn", "message": "must be a positive integer" }
  ]
}

Each issue includes a path (dot-separated field path) and a message describing the constraint that failed.

Common HTTP status codes

Status	Description
`400`	Invalid request body — missing required fields, wrong types, or failed validation
`401`	Missing or invalid API key
`404`	Resource not found
`409`	Resource state conflict (e.g., re-claiming a completed link)
`410`	Resource has expired
`502`	Upstream service failure

Platform session errors

Code	Description
`session_expired`	Session has timed out
`session_terminal`	Session is in a terminal state (complete/failed/expired)
`command_pending`	A command is already in flight