Errors

Every error response has the same three fields, whatever the endpoint:

{
  "code": "INVALID_CREDENTIALS",
  "message": "Invalid credentials",
  "docs_url": "https://dev.flowawsome.com/errors/invalid-credentials"
}

Branch on code. It is stable; message is English text meant for logs and may change.
The same code can come with more than one HTTP status, and one status can carry many codes, so use the status for the retry decision and the code for everything else.
docs_url links to this page for the code.

400 Bad Request

The request was rejected as sent. Fix the request body, query, or path parameters before retrying; sending the same request again will fail the same way.

BAD_REQUESTThe request could not be processed.
CURRENT_PASSWORD_INVALIDCurrent password is incorrect
DELEGATE_CANNOT_BE_DELEGATORA delegation must point at a different person
DELEGATION_SCHEDULE_EMPTYThe schedule has no shift between those dates
HR_ATTRIBUTE_INVALID
HR_ATTRIBUTE_NOT_DEFINED
HR_CREDENTIALS_REQUIREDclientSecret, signedCertificate and privateKey are required when no configuration exists yet
INVALID_CURSORafter is not a cursor this feed returned
MFA_NOT_ENABLEDTwo-factor authentication is not enabled for this account
MFA_REAUTH_FAILEDThe authenticator or backup code is incorrect
MFA_REAUTH_REQUIREDEnter a code from your authenticator app or a backup code to change two-factor authentication
MFA_REGISTRATION_NOT_PENDINGNo pending MFA registration for this account
MFA_TOTP_CODE_INVALIDInvalid TOTP code
PASSWORD_CHANGE_NOT_REQUIREDPassword change is not required for this account
PASSWORD_NOT_SETThis account signs in without a password
RESOLUTION_KEY_MISMATCHuserId must be omitted or be your own user id on this route
SAML_CERTIFICATE_REQUIREDidpCertificate is required when no SAML configuration exists yet
SSO_NONCE_INVALIDnonce must be the sha256 hex of the client nonce
VALID_UNTIL_IN_PASTvalidUntil must be in the future. To end an assignment now, remove it.
VALIDATION_ERROR

401 Unauthorized

The credential is missing, invalid, or expired. Refresh the session or sign in again for bearer tokens; check the X-Api-Key value for API keys.

API_KEY_CONTEXT_MISSINGApiKeyScopeGuard requires ApiKeyAuthGuard to run first
API_KEY_EXPIREDAPI key has expired
API_KEY_INVALIDInvalid API key
API_KEY_MISSING
API_KEY_REVOKEDAPI key has been revoked
BEARER_TOKEN_MISSINGMissing bearer token
INVALID_CREDENTIALSInvalid credentials
INVALID_REFRESH_TOKENInvalid refresh token
MFA_CHALLENGE_INVALIDInvalid or expired MFA challenge
MFA_CODE_INVALIDInvalid MFA code
OAUTH_EMAIL_MISSINGProvider did not return a verified email
OAUTH_STATE_INVALIDInvalid or expired state
OAUTH_STATE_MISSINGMissing state
SAML_ASSERTION_INVALIDInvalid SAML assertion
SAML_STATE_INVALIDInvalid or expired sign-in state
SESSION_EXPIREDSession expired or revoked
SSO_CODE_INVALIDInvalid or expired sign-in code
UNAUTHORIZEDAuthentication is required.

403 Forbidden

The caller is authenticated but not allowed to do this (role, key type or scope, or an organization policy). Retrying without changing the credential or the configuration will not help.

ADMIN_CONSOLE_FEATURE_DENIED
API_KEY_CONTEXT_MISSINGApiKeyScopeGuard requires ApiKeyAuthGuard to run first
API_KEY_PURPOSE_NOT_ALLOWED
API_KEY_SCOPE_MISMATCHAPI key scope does not cover this service
API_KEY_TYPE_NOT_ALLOWEDPublishable keys cannot call this endpoint — use a secret key from your server
APPROVER_CANNOT_BE_ACTORYou cannot reassign a step to yourself
CANNOT_CONFIRM_OWN_RECOVERYAnother administrator has to confirm this request
CANNOT_DEACTIVATE_SELFYou cannot change your own account status
CANNOT_DEMOTE_SELFYou cannot remove your own admin role — ask another admin to do it
CHANGE_REVIEW_NOT_ALLOWEDThis change set includes changes you are not allowed to make.
CHANGE_REVIEW_SELFWithdraw your own change set instead of rejecting it.
CHANGE_SET_NOT_YOURSOnly the author can publish this change set.
DELEGATE_CANNOT_BE_ACTORYou cannot delegate someone else’s approvals to yourself
DEPARTMENT_CYCLE_DETECTEDAssigning this parent would create a cycle in the department hierarchy
DEPARTMENT_ORG_MISMATCHDepartment must belong to the same organization
DEPARTMENT_PARENT_ORG_MISMATCHParent department must belong to the same organization
FORBIDDENForbidden resource
FOUNDER_REQUIREMENT_NOT_METThis action is restricted by system policy
JOB_TITLE_ORG_MISMATCHThat job title belongs to a different organization
LAST_ADMIN_PROTECTEDThis worker is the only active admin left — promote someone else before the HR system deactivates them
MANAGER_CYCLE_DETECTEDAssigning this manager would create a cycle in the reporting chain
MFA_SETUP_REQUIREDComplete MFA setup before accessing this resource
OAUTH_LOGIN_DISABLEDOAuth login is not enabled for this organization
ORG_SCOPE_VIOLATIONToken organization is not within the required scope of the target organization
PASSWORD_CHANGE_REQUIREDChange your temporary password before accessing this resource
REASSIGN_OWN_REQUESTYou cannot change who approves a request you raised
RESERVED_RESOURCE_TYPE
ROLE_FILTER_NOT_ALLOWEDThis organization does not show members' roles to you, so the list cannot be filtered by role.
ROLE_REQUIREMENT_NOT_METAn organization-wide secret key can only be issued by an org_admin
SELF_SIGNUP_DISABLEDSelf-signup is disabled for this organization
SERVICE_ACCESS_DENIEDNot authorized to access this service
SERVICE_ID_PARAM_MISSINGApiKeyScopeGuard requires a :serviceId route param
SERVICE_NOT_FOUNDTarget service not found
STEP_UP_NOT_AVAILABLEThis action is not available in a support session
STEP_UP_REQUIREDConfirm your password to continue
SUPPORT_SESSION_FORBIDDENChange review settings cannot be changed from a support session
SYSTEM_WORKFLOW_DEFINITIONThis approval chain is managed by the system and cannot be edited or deleted
SYSTEM_WORKFLOW_INSTANCEThis request is managed by the system and its approver cannot be changed

404 Not Found

The resource does not exist, or it is not visible to this caller. Check the identifier and that it belongs to the organization the credential is for.

API_KEY_NOT_FOUND
APP_NOT_FOUNDApp not found
CHANGE_NOT_FOUNDThat change is not in this change set
CHANGE_SET_NOT_FOUNDChange set not found
CREDENTIAL_CHANGE_NOT_FOUNDNo pending credential change with this id
DELEGATE_NOT_FOUNDUser not found
DELEGATION_NOT_FOUNDDelegation not found
DEPARTMENT_NOT_FOUNDParent department not found
GRANT_NOT_FOUNDadmin_console_feature_grants row not found
INITIATOR_NOT_FOUNDinitiatorUserId does not resolve to a user in this tenant
JOB_TITLE_NOT_FOUNDJob title not found
MANAGER_NOT_FOUNDManager not found in this organization
NOT_FOUNDThe requested route or resource does not exist.
OAUTH_PROVIDER_UNSUPPORTED
ORGANIZATION_NOT_FOUNDOrganization not found
RECOVERY_REQUEST_NOT_FOUNDRecovery request not found
SAML_CONFIG_NOT_FOUND
SERVICE_NOT_FOUNDTarget service not found
SESSION_NOT_FOUNDSession not found
STRIPE_ACCOUNT_NOT_FOUNDNo Stripe billing account is connected for this organization
TRUSTED_BFF_CREDENTIAL_NOT_FOUNDCredential not found or already revoked
USER_NOT_FOUNDUser not found in this organization
WORKFLOW_INSTANCE_NOT_FOUND
WORKFLOW_STEP_NOT_FOUND

409 Conflict

The request conflicts with the current state of the resource. Re-read the resource, then decide whether to change the request.

ACTIVE_INTEGRATIONS_REMAIN
APP_IN_USEThis app is still referenced by API keys, webhooks, approval chains or past requests. Retire it instead
APP_SLUG_ALREADY_EXISTSAn app with this slug already exists in this organization
APPROVER_ALREADY_ACTEDThis person has already acted on this request
APPROVER_CANNOT_BE_INITIATORThe person who raised the request cannot approve it
APPROVER_NOT_ACTIVEOnly an active member can head a department
CHANGE_AUTHOR_INACTIVEThe author of this change is no longer active, so it can't be applied.
CHANGE_PRECONDITION_FAILED
CHANGE_REVIEW_NOT_REQUIREDThis organization does not require review — publish the change instead.
CHANGE_REVIEW_REQUIREDAnother admin must publish this change. Submit it for review.
CHANGE_SET_NOT_EDITABLE
CHANGE_STALEThis was changed after you opened the page. Reload it and make your change again.
DEPARTMENT_HIERARCHY_MANAGED_BY_HRThis department is placed by the HR sync; move it in the HR system instead
DEPARTMENT_IN_USE
EMAIL_ALREADY_EXISTSAn account with this email already exists
EXTERNAL_WORKER_IDENTITY_CONFLICTThis email or employee ID already belongs to an account linked to a different HR record
FOUNDER_PROTECTEDThis account is protected by system policy and cannot be deactivated by an HR sync
HR_ATTRIBUTE_DEFINITIONS_STALEThese HR attributes were changed by someone else. Reload and try again
IP_ALLOWLIST_EXCLUDES_CURRENT_IPThe allow list must include the network you are signed in from
JOB_FUNCTION_RANK_MAPPING_DUPLICATEEach job function (including the blank one) can only appear once
JOB_FUNCTION_RANK_MAPPINGS_STALEThese mappings were changed by someone else — reload and try again
JOB_TITLE_DEPARTMENT_MISMATCHThat job title is not the one this member's department uses for its rank
JOB_TITLE_IN_USE
JOB_TITLE_RANK_ALREADY_EXISTSA job title with this rank level already exists in this scope
JOB_TITLE_RANKS_DEPARTMENT_TITLESA department has its own job title at one of these ranks, so moving the job function mapping would change its members' titles. Reorder that department's titles first, or keep the mapping where it is.
JOB_TITLE_RANKS_STALEThe job titles in this scope have changed — reload and try again
LAST_ADMIN_PROTECTEDThis worker is the only active admin left — promote someone else before the HR system deactivates them
LOGIN_POLICY_EXCLUDES_EVERYONENo member who signs in with a password would be able to sign in under this policy.
LOGIN_POLICY_EXCLUDES_SELFThis policy would stop you from signing in with your own account.
PASSWORD_NOT_SETThis account signs in without a password
PRIVILEGED_IDENTIFIER_PROTECTEDThis worker is an administrator; their sign-in email and employee id cannot be changed by an HR sync
QUORUM_UNREACHABLE
RECOVERY_ALREADY_CONFIRMEDThis request has already been confirmed
RECOVERY_CONFIRMATION_NOT_REQUESTEDThis request was verified another way and needs no confirmation
RECOVERY_NOT_PENDING
SERVICE_IN_USEThis service is still referenced by API keys, webhooks, approval chains or past requests. Retire it instead
SERVICE_SLUG_ALREADY_EXISTSA service with this slug already exists in this app
SLUG_ALREADY_EXISTSAn organization with this slug already exists
WORKFLOW_INSTANCE_NOT_IN_PROGRESSOnly a request that is still in progress can be reassigned
WORKFLOW_STEP_ALREADY_ACTIONEDA step that has already been approved or rejected cannot be reassigned
WORKFLOW_STEP_NOT_IN_APPROVAL_PATHThis request has no recorded approver for that step

422 Unprocessable Entity

The request is well-formed but cannot be carried out with the current configuration (for example, no approver could be resolved). Fix the configuration, then retry.

CHANGE_EXPECTED_REQUIREDAn approval chain draft must say which version of the chain it was edited from.
CHANGE_REASON_REQUIREDThis organization requires a reason for every change.
CHANGE_REVIEW_WHOLE_SETA change set under review is published as a whole. Reject it if some of it should not go out.
CHANGE_SET_EMPTYThere is nothing to publish in this change set.
ROOT_ORGANIZATION_SETTINGSet this on the top-level organization. Subsidiaries follow it.

429 Too Many Requests

A rate limit was hit. Wait before retrying; when a Retry-After header is present, wait at least that many seconds.

LOGIN_RATE_LIMITEDToo many login attempts
MFA_VERIFY_RATE_LIMITEDToo many MFA verification attempts
ONBOARDING_RATE_LIMITEDToo many signup attempts
SIGNUP_RATE_LIMITEDToo many signup attempts
TOO_MANY_REQUESTSToo many requests.

500 Internal Server Error

Something failed on our side. Retry with exponential backoff; if it keeps happening, contact support with the time of the request.

INTERNAL_SERVER_ERRORInternal server error

503 Service Unavailable

The service is temporarily unavailable. Retry with exponential backoff.

SESSION_STORE_UNAVAILABLESession store is temporarily unavailable