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

StatusDescription
400Failed validating your request
401There’s an issue with your API key
404The resource you’re trying to access doesn’t exist
422The request cannot be processed, check the error code for more details
429You’ve exceeded the rate limits
500An 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

Status400
DescriptionRequest is invalid.
RemedyAdjust the request body & parameters and try again.

​
unauthorized

Status401
DescriptionAuthorization failed.
RemedyVerify that your API key is correct and you’re passing it correctly in the request.

​
not_found

Status404
DescriptionResource not found.
RemedyCheck the resource URL.

​
coverage_request_not_pending

Status422
DescriptionCannot take action on a coverage request that is not in the pending state.
Remedy-

​
coverage_request_self_owned

Status422
DescriptionCannot accept or decline own coverage request.
Remedy-

​
too_many_shifts_in_coverage_request

Status422
DescriptionThere are too many shifts in the coverage request you are trying to create.
RemedyAdjust the time interval for the coverage request so that it contains no more than 500 shifts.

​
override_already_finished

Status422
DescriptionOverrides that have already finished cannot be updated or deleted. They can only be read.
Remedy-

​
duplicate_schedule_name

Status422
DescriptionA schedule with this name already exists.
RemedyTry a different name.

​
invalid_user_reference

Status422
DescriptionAt least one of the provided user references refers to a user that does not exist.
RemedyAdjust the user references and try again.

​
duplicate_team_name

Status422
DescriptionA team with this name already exists.
RemedyTry a different name.

​
slack_group_permission_denied

Status422
DescriptionMissing permissions to create user groups.
RemedyCheck our guide to troubleshoot Slack permissions for user groups.

​
slack_group_only_available_for_paid_teams

Status422
DescriptionUser groups are available only on paid Slack plans.
RemedyUpgrade your Slack workspace to a paid plan.

​
slack_group_duplicate_handle_name

Status422
DescriptionA Slack user group with this handle already exists.
RemedyTry a different handle.

​
slack_group_duplicate_name

Status422
DescriptionA Slack user group with this name already exists.
RemedyTry a different name.

​
too_many_requests

Status429
DescriptionRate limit exceeded.
RemedyWait for the rate limit to reset.

​
internal_server_error

Status500
DescriptionAn internal error occurred in our system.
RemedyTry again later.
VersionsList schedules