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.