Skip to main content
Three refusals come from checking who is calling, rather than from the request’s content. Each uses the shared response format: branch on message.token, and read the details from message.tokenArguments. The status codes follow RFC 9110. In none of the three is anything saved. They are being switched on account by account as roles roll out, so handle them now rather than when you first see one.

403 insufficient_permissions

The caller is known, but its role where the request applies does not include the permission the operation needs (RFC 9110, section 15.5.4). missingPermission names it.
What to do. Give the person or API token a role that includes missingPermission for that organisation, or have somebody who holds it make the request. Each operation names its permission in x-flow-permission; see Users, roles and permissions. An API token also gets this answer when it tries to create, change or delete a role, because a token never holds a role permission.

400 field_not_writable

The request changes a detail that nobody can change through this operation, such as isLeaver, which Flow Payroll sets itself (RFC 9110, section 15.5.1). More access never fixes it: the request itself has to change. fields lists the details.
What to do. Remove the listed details from the request, or send them unchanged, and use the operation made for them. For example, record a leaver with PUT /employees/{employeeId}/leaver.

503 access_check_unavailable

Flow Payroll could not check access for this request just now (RFC 9110, section 15.6.4). It is never a refusal: the request was not judged, and nothing was saved. The Retry-After header gives the number of seconds to wait (RFC 9110, section 10.2.3).
What to do. Wait at least Retry-After seconds and send the same request again. Back off further if it repeats, and contact support if it keeps happening.

Other access refusals

Managing access in the Administration API has refusals of its own, such as role_not_yet_available, role_assignment_denied, access_management_denied, whole_customer_access_denied, duplicate_access and access_with_deprecated_fields. Each operation lists the ones it can answer.