Errors

All integrator errors use a single envelope. Messages are safe for clients; internal details are never exposed.

Error shape

Error envelopejson

{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid API key.",
    "requestId": "..."
  }
}

Optional details may appear for validation issues or rate limit metadata such as retryAfterSeconds. Successful JSON responses also include an X-Request-Id header.

Verified error codes

HTTP	Code	Meaning
400	invalid_request	Malformed JSON, missing required headers, or schema validation failure.
401	unauthenticated	Missing or invalid API key, environment mismatch, or revoked credential.
403	permission_denied	Authenticated but lacking scope, universe not allowed, or Discord guild mismatch.
404	not_found	Resource not found, or staff/Roblox identity not linked.
409	conflict	Idempotency key reused with a different payload, or conflicting shift state.
422	unprocessable	Business rule violation (timestamps, shift status, duration limits).
429	rate_limited	Too many requests. Response may include Retry-After.
500	internal_error	Unexpected server error. Message is always generic.
403	discord_integration_not_connected	Discord is not connected for this workspace.
403	discord_guild_mismatch	X-Discord-Guild-Id does not match the connected binding.
403	discord_integration_suspended	Discord integration is suspended.
403	discord_integration_revoked	Discord integration has been revoked.
404	discord_user_unlinked	No staff profile is linked to the acting Discord user.
404	roblox_user_unlinked	Staff profile has no linked Roblox identity.
403	feature_not_enabled	Requested feature is not enabled for the workspace.