Errors

We follow standard HTTP status codes to indicate API response status:

Status	Description
`400`	Failed validating your request
`401`	There’s an issue with your API key
`404`	The resource you’re trying to access doesn’t exist
`422`	The request cannot be processed, check the error code for more details
`429`	You’ve exceeded the rate limits
`500`	An internal error occurred in our system

Error shape

Errors are returned as JSON, with a top-level error object that includes code, message, status and optionally docs_url. Here’s an example:

{
    "error": {
        "code": "duplicate_team_name",
        "docs_url": "http://docs.shiftkeeper.io/api-reference/teams/create-a-team",
        "message": "A team with this name already exists",
        "status": 422
    }
}

Error codes

This section provides a list of error codes that the API might return.

`bad_request`


Status	400
Description	Request is invalid.
Remedy	Adjust the request body & parameters and try again.

`unauthorized`


Status	401
Description	Authorization failed.
Remedy	Verify that your API key is correct and you’re passing it correctly in the request.

`not_found`


Status	404
Description	Resource not found.
Remedy	Check the resource URL.

`coverage_request_not_pending`


Status	422
Description	Cannot take action on a coverage request that is not in the `pending` state.
Remedy	-

`coverage_request_self_owned`


Status	422
Description	Cannot accept or decline own coverage request.
Remedy	-

`too_many_shifts_in_coverage_request`


Status	422
Description	There are too many shifts in the coverage request you are trying to create.
Remedy	Adjust the time interval for the coverage request so that it contains no more than 500 shifts.

`override_already_finished`


Status	422
Description	Overrides that have already finished cannot be updated or deleted. They can only be read.
Remedy	-

`duplicate_schedule_name`


Status	422
Description	A schedule with this name already exists.
Remedy	Try a different name.

`invalid_user_reference`


Status	422
Description	At least one of the provided user references refers to a user that does not exist.
Remedy	Adjust the user references and try again.

`duplicate_team_name`


Status	422
Description	A team with this name already exists.
Remedy	Try a different name.

`slack_group_permission_denied`


Status	422
Description	Missing permissions to create user groups.
Remedy	Check our guide to troubleshoot Slack permissions for user groups.

`slack_group_only_available_for_paid_teams`


Status	422
Description	User groups are available only on paid Slack plans.
Remedy	Upgrade your Slack workspace to a paid plan.

`slack_group_duplicate_handle_name`


Status	422
Description	A Slack user group with this handle already exists.
Remedy	Try a different handle.

`slack_group_duplicate_name`


Status	422
Description	A Slack user group with this name already exists.
Remedy	Try a different name.

`too_many_requests`


Status	429
Description	Rate limit exceeded.
Remedy	Wait for the rate limit to reset.

`internal_server_error`


Status	500
Description	An internal error occurred in our system.
Remedy	Try again later.

Using the API

Schedules

Overrides

Coverage

Shifts

Users

Teams

Error shape

Error codes

`bad_request`

`unauthorized`

`not_found`

`coverage_request_not_pending`

`coverage_request_self_owned`

`too_many_shifts_in_coverage_request`

`override_already_finished`

`duplicate_schedule_name`

`invalid_user_reference`

`duplicate_team_name`

`slack_group_permission_denied`

`slack_group_only_available_for_paid_teams`

`slack_group_duplicate_handle_name`

`slack_group_duplicate_name`

`too_many_requests`

`internal_server_error`

​Error shape

​Error codes

​bad_request

​unauthorized

​not_found

​coverage_request_not_pending

​coverage_request_self_owned

​too_many_shifts_in_coverage_request

​override_already_finished

​duplicate_schedule_name

​invalid_user_reference

​duplicate_team_name

​slack_group_permission_denied

​slack_group_only_available_for_paid_teams

​slack_group_duplicate_handle_name

​slack_group_duplicate_name

​too_many_requests

​internal_server_error

Error shape

Error codes

`bad_request`

`unauthorized`

`not_found`

`coverage_request_not_pending`

`coverage_request_self_owned`

`too_many_shifts_in_coverage_request`

`override_already_finished`

`duplicate_schedule_name`

`invalid_user_reference`

`duplicate_team_name`

`slack_group_permission_denied`

`slack_group_only_available_for_paid_teams`

`slack_group_duplicate_handle_name`

`slack_group_duplicate_name`

`too_many_requests`

`internal_server_error`