Skip to content
Round RobinRound Robin

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

Section titled “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 Another write changed the resource while your request was in progress, and nothing was applied. Read it again and retry with the new ETag.
user_group_not_manageable 409 Ask a Slack admin to review user-group permissions or choose a manageable group.
external_rotation_is_read_only 409 Change the rotation in PagerDuty or Jira Service Management. Who is on call, and when, comes from there.
webhook_endpoint_limit 409 The workspace already has the maximum of 10 webhook endpoints. Delete one you no longer use, then register again.
webhook_url_malformed 400 Send a complete https URL, host and path included.
webhook_url_scheme_not_allowed 400 Use https.
webhook_url_host_not_resolvable 400 Check the host name. It resolves to no address.
webhook_url_private_address 400 Use an address reachable from the public internet. The detail names the refused range.
webhook_event_type_unknown 400 Use only duty.changed, nobody.on_call, rotation.created, rotation.updated and rotation.deleted in eventTypes.
webhook_event_type_not_subscribable 400 Remove webhook.test from eventTypes. A test event arrives without a subscription.

A webhook_endpoint_limit refusal reads:

{
  "title": "The workspace holds the maximum number of endpoints",
  "status": 409,
  "detail": "A workspace holds at most 10 webhook endpoints. Delete one you no longer use to register another: https://docs.roundrobinbot.eu/api/webhooks/",
  "code": "webhook_endpoint_limit"
}

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

Section titled “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

Section titled “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

Section titled “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

Section titled “Next steps”