Errors
Every error from every route has one shape:
{
"error": {
"code": "scope_missing",
"message": "The session was not minted with company:write",
"correlationId": "c_01JCG3Q0…",
"fields": [{ "path": "abn", "code": "invalid", "message": "11 digits" }],
"stepUp": { "intentId": "…", "authorizeUrl": "https://…" },
"blockers": [{ "code": "employee_details_incomplete", "message": "…" }]
}
}
code is stable and machine-readable; message is for a developer and may change; correlationId (also the X-Correlation-Id response header) matches Payroo's audit record, so quote it when you write to Payroo. fields[] appears on validation errors, stepUp on step_up_required, blockers[] on a 409 precondition_required from a pay run action.
The React components handle every code below themselves: a blocked state and a new session for 401, inline field errors for 422, the Payroo dialog for step-ups, a reload for conflicts. Your server sees them on the routes it calls itself.
Codes by status
401: no usable credential or session
| Code | Meaning | Next action |
|---|---|---|
invalid_credential |
unknown or revoked partner credential on x-api-key |
check the secret your server holds; after a revocation, use the new credential |
credential_expired |
the credential's expiresAt has passed (rotation overlap over) |
switch to the credential Payroo issued for the rotation |
invalid_token |
missing, malformed or tampered session token; also a token signed by anything but Payroo's ES256 key | mint a new session; never construct tokens |
session_expired |
the session's lifetime ended | the runtime asks your session route for a new one |
session_revoked |
the session was revoked (DELETE /sessions/{id} or POST /sessions/revoke) |
mint a new session if the user still should have one |
403: the caller is known, the action is not allowed
| Code | Meaning | Next action |
|---|---|---|
forbidden |
a partner credential on a staff route, or vice versa | use the right credential kind |
host_origin_not_allowed |
hostOrigin is not in your record's allowedOrigins |
send the page's exact origin; add sandbox origins in the portal; ask Payroo for production origins |
employer_not_delegated |
the company is not delegated to your partner | provision it through POST /employers, or ask Payroo for a delegation of an existing company |
user_not_member |
the mapped Payroo user is not an admin of that company (employer session) | only organisation admins may hold employer sessions; map the right user or ask the company's admin |
component_not_enabled |
a component not enabled on your record | ask Payroo to enable it |
scope_exceeds_maximum |
a scope beyond your record's maxScopes |
request only allowed scopes |
scope_missing |
the route needs a scope the session lacks | mint with the scopes the page needs |
component_not_in_session |
the route belongs to a component not in the session | mint with the components the page mounts |
not_owner |
another partner's session (refresh, bootstraps, revoke) | only the minting partner may act on a session |
step_up_required |
the action needs the user's confirmation with Payroo; error.stepUp.authorizeUrl carries the dialog |
the component opens the dialog and retries with X-Step-Up-Intent |
approval_intent_required |
a pay run approval without an approval intent from the confirmation frame | use the component; a bare session cannot approve |
support_delegation_required |
a Payroo staff read of a company without an active support delegation | staff only |
404
| Code | Meaning | Next action |
|---|---|---|
not_found |
the resource does not exist or belongs to another company; ids are never disclosed across companies | check the id and the company the session is for |
invitation_invalid |
an invitation token nobody issued, or one already used or expired | send a new invitation (POST /employees/{id}/invitations) |
409: the current state refuses the action
| Code | Meaning | Next action |
|---|---|---|
revision_conflict |
your If-Match is stale |
reload the resource, re-apply, retry with the new ETag |
precondition_required |
a prerequisite is missing: the ATO details not reviewed before notify; a pay run blocked (blockers[] lists why: older_draft_exists, employee_tax_details_missing, employee_details_incomplete, payer_apca_id_missing, payer_bank_details_invalid, subscription_inactive) |
resolve each blocker; GET /payruns/{id}/readiness reports the same list |
payrun_not_editable |
the pay run is not in a state that allows the action (reopen a draft, edit an approved run) | read state first |
payrun_not_approved |
lodge or payment file on an unapproved pay run | approve first |
payrun_period_overlap |
a new pay run overlaps an existing period | choose a period after the last run |
abn_exists_elsewhere |
the ABN belongs to another organisation | use the company's own ABN; in the sandbox generate another |
operation_not_resumable |
resume of an operation that already succeeded, or is running | read GET /operations/{id} |
operation_not_resolvable |
staff resolution of an operation that is not a stuck lodgement | staff only |
410: gone
| Code | Meaning | Next action |
|---|---|---|
approval_intent_expired |
the approval intent expired before the approval | start the approval again |
session_hard_limit |
a refresh on a session created more than eight hours ago | mint a new session |
A step-up intent that passed its ten-minute window reads as expired on GET /step-up/intents/{intentId}; the component starts the action again.
422: the request is understood and wrong
| Code | Meaning | Next action |
|---|---|---|
validation_failed |
a field is invalid; fields[] has path, code, message |
fix the fields; the forms show them inline |
idempotency_body_mismatch |
an Idempotency-Key reused with a different body |
one key per attempt; the same key only for an identical retry |
field_locked |
a field your partner record locks (set by Payroo) | contact Payroo |
invalid_handle |
a secure-value handle that is not valid, not yours or already used | capture the value again through the secure field |
webhook_destination_invalid |
the webhook URL is not https on 443 or not a public address | use a public https receiver |
428 and 429
| Status and code | Meaning | Next action |
|---|---|---|
428 precondition_required |
a pay run mutation without If-Match |
send the ETag you read |
429 rate_limited |
the per-partner (600/min) or per-session (120/min) window is exhausted | wait Retry-After seconds |
Validation field codes
fields[].code values you will meet: required, invalid, bank_account_number (5 to 9 digits), payroo_email (the address belongs to a Payroo staff domain), target_origin, partner_link, super_settings, payments_account. The message says what to change.
Operations that need attention
Provisioning and lodgement run as operations. GET /operations/{id} reports state (running, succeeded, failed) and each step. A failed provisioning resumes with POST /operations/{id}/resume. A lodgement that Payroo could not complete is marked needs_attention; Payroo staff resolve it and the outcome reaches you through payrun.accepted or payrun.rejected.