Errors

API refusals identify the status and, where supplied, a machine-readable code. Use the code to choose recovery; display the title and available detail to the person reviewing the error.

The codes

code	Status	What to do
missing_credential	401	Send a team API key for the key-authenticated operation.
unknown	401	Check the key and environment. Replace a revoked key.
disabled	401	Ask a workspace admin to review the key.
expired_secret	401	Use the current secret.
scope_denied	403	Use a key with the required scope.
resource_denied	403	Check the key’s selected rotations and workspace.
invalid_request	400	Correct the request. Where the response names a parameter, start there.
precondition_required	428	Supply the required If-Match or creation idempotency header.
precondition_failed	412	Refresh, review the current resource and retry with its ETag.
rate_limited	429	Wait for Retry-After before retrying.
payment_required	402	Check the workspace plan and requested limits.
write_conflict	409	Refresh the resource before retrying.
user_group_not_manageable	409	Ask a Slack admin to review user-group permissions or choose a manageable group.

The credential codes above apply to team API keys. Participant actions have a different credential requirement. See authentication and participant duty operations for cover, swap and availability-preview refusals.

Statuses without a code

Status	What to do
304 Not Modified	Use the cached response; this is not a refusal.
404 Not Found	Check the identifier and workspace access. An inaccessible resource can appear missing.
409 Conflict	Read the response before retrying. A rotation shape or an expired creation retry key may require a changed request.
500	Retry after checking the current result. If reproducible, contact support with the operation and time, without credentials.

Check access before retrying

GET /v1/keys/self shows a team key’s scopes and selector. A 403 from a restricted key can require a different key; repeating the request cannot expand its access.

A 412 means the supplied version does not match. Read or preview again. Sending the same stale validator repeats the refusal.

For an uncertain duty write, retain its operation identifier. Use an identical retry to resolve that attempt before starting a new one.

Bad input is refused, not corrected

Check the operation’s accepted fields and values. Unknown sort fields and unsupported expansion values are refused instead of silently changing the query.

A person is on a rotation’s list once. POST /v1/rotations with the same id twice in userIds answers 400 with invalid_request, and creates nothing. The response does not name the repeated id, so check userIds for duplicates, remove them and send the request again.

Next steps

• Authentication: choose the credential for the operation.
• Scopes and access: inspect key permissions.
• Conventions: send validators and page through results.
• Participant duty operations: recover from duty-specific refusals.