Error codes¶

When an API request fails, Permission Assist returns an HTTP error status code and a JSON response body with details about the error.

Error response format¶

All error responses share this structure:

{
  "error": "validation_error",
  "message": "One or more validation errors occurred",
  "correlationId": "a1b2c3d4e5f67890abcdef1234567890"
}

Field	Type	Description
`error`	string	A machine-readable error code
`message`	string	A human-readable description of the error
`correlationId`	string (GUID)	A unique identifier for this error occurrence, useful for troubleshooting with support

Errors that involve field-level validation include an additional errors array with details about each invalid field:

{
  "error": "validation_error",
  "message": "One or more validation errors occurred",
  "correlationId": "a1b2c3d4e5f67890abcdef1234567890",
  "errors": [
    {
      "field": "identity.firstName",
      "message": "First name is required"
    },
    {
      "field": "effectiveDate",
      "message": "Effective date is required"
    }
  ]
}

Field	Type	Description
`errors[].field`	string	The name of the request field that caused the error
`errors[].message`	string	A human-readable description of the problem

Error codes¶

`error` value	HTTP Status	Description
`validation_error`	400	One or more request fields are missing or invalid
`unauthorized`	401	The API token is missing, invalid, or expired
`forbidden`	403	The request is authenticated but not authorized
`not_found`	404	The requested resource does not exist
`conflict`	409	The resource is in a state that conflicts with the request
`unprocessable_entity`	422	The request is valid but a precondition is not met
`server_error`	500	An unexpected error occurred on the server
`creation_failed`	500	The resource could not be created due to a server-side error

HTTP status codes¶

Status	Meaning
`200`	The request succeeded
`201`	The resource was created successfully
`204`	The request succeeded with no response body
`400`	The request was invalid. Check the `errors` array for details about which fields are missing or malformed
`401`	Authentication failed. The API token is missing, invalid, or expired
`403`	Access denied. The request is authenticated but not authorized
`404`	The requested resource was not found
`409`	Conflict. The request cannot be completed because the resource is in a conflicting state (for example, canceling an import that has already finished)
`422`	Unprocessable request. The request is valid but cannot be completed because a precondition is not met (for example, the application does not have an import schedule configured)
`500`	Server error. An unexpected error occurred

Common errors and solutions¶

Error	Likely cause	Solution
`401 Unauthorized`	Missing or invalid `Authorization` header	Verify the token is correct and has not been deleted or expired. Refer to Authentication
`400 Bad Request` with `errors` array	One or more required fields are missing or contain invalid values	Review the `errors` array in the response body for the specific fields that failed validation
`404 Not Found`	The resource ID does not match any record in Permission Assist	Verify the ID exists in Permission Assist before making the request
`409 Conflict` (import cancel)	The import has already finished, failed, or been canceled	Check the current import status before attempting to cancel
`422 Unprocessable` (import stage)	The application does not have an import schedule configured, or the connector is not available	Configure an import schedule for the application before using the stage endpoint