Error Handling
API error codes, formats, and retry behaviorEdit
Error Response Format
All error responses return a JSON body with an error field:
{
"error": "Not found"
}Some errors include additional context:
{
"error": "Validation failed",
"details": [
{ "field": "name", "message": "Name is required" }
]
}HTTP Status Codes
| Status | Meaning | Action |
|---|---|---|
200 | Success | — |
201 | Created | Resource created successfully |
400 | Bad Request | Fix the request body or parameters |
401 | Unauthorized | Credentials are missing, invalid, expired or revoked. Check the token |
402 | Subscription required | Supercheck Cloud only: the organization needs an active subscription for this action (for example resuming a monitor after a trial ended) |
403 | Forbidden | Authenticated but not permitted: RBAC role, project scope, or browser-only operation. Admin-only (/api/admin/*) endpoints return 401 when signed out and 403 for non-admins |
404 | Not Found | Verify the resource ID exists. A resource in an organization you do not belong to also returns 404, the same as a missing ID |
409 | Conflict | Duplicate resource (e.g. token name) |
429 | Rate Limited | Wait and retry (see Retry-After header) |
500 | Server Error | |
503 | Service Unavailable | A safety limiter or dependency is unavailable (for example the invitation or API-key verification limiter while Redis is down). Retry after the Retry-After interval |
Retry Behavior
The CLI retries rate-limited requests and selected transient errors. It does not automatically replay POST or PATCH requests after server or network failures.
| Error | What to do |
|---|---|
429 rate limit | Let the CLI wait and retry. In your own client, respect Retry-After when present. |
5xx or network failure | Safe-to-repeat requests use backoff. Before repeating a create, update, or trigger, check whether it already succeeded. |
Other 4xx responses | Fix the request, credentials, or permissions before retrying. |
| Request timeout | Check connectivity and the operation's result before issuing it again. |
Retry-After Header
When rate limited, the server returns a Retry-After header with the number of seconds to wait:
HTTP/1.1 429 Too Many Requests
Retry-After: 60The CLI parses this header safely — non-numeric or negative values fall back to exponential backoff instead of causing a tight retry loop.
CLI Exit Codes
The CLI maps errors to specific exit codes for scripting and CI/CD:
| Exit Code | Meaning | Example |
|---|---|---|
0 | Success | Job completed, resource created |
1 | General error | Test failed, validation error |
2 | Authentication error | Invalid token, expired token |
3 | Configuration error | Missing config, invalid schema |
4 | Network / API error | API unreachable, 5xx response |
5 | Timeout | Operation exceeded --timeout |
CI/CD Usage
# Capture exit code before it's overwritten by subsequent commands
export SUPERCHECK_TRIGGER_KEY="sck_trigger_..."
export SUPERCHECK_TOKEN="sck_live_..." # required here because --wait polls the run
supercheck job trigger $JOB_ID --wait
exit_code=$?
if [ $exit_code -eq 0 ]; then
echo "All tests passed"
elif [ $exit_code -eq 1 ]; then
echo "Tests failed"
elif [ $exit_code -eq 2 ]; then
echo "Authentication issue — check SUPERCHECK_TRIGGER_KEY and, when using --wait, SUPERCHECK_TOKEN"
fiCommon Errors
Invalid Token
HTTP/1.1 401 Unauthorized
{"error": "Invalid or expired CLI token"}The message varies (for example Authentication required, or Invalid token type for a trigger key used on a general endpoint).
Fix: Verify your token is valid with supercheck whoami. Create a new token if needed.
Token Expired or Revoked
Expired, disabled and revoked tokens return 401 Unauthorized.
Fix: Run supercheck login --reauth or create a new token in the dashboard.
Insufficient Permissions
HTTP/1.1 403 Forbidden
{"error": "Insufficient permissions"}Fix: The CLI token inherits the creating user's RBAC role and is limited to one project. Ask an org admin to adjust your role, or use a token for the right project. Organization administration needs a browser session.
Resource Not Found
HTTP/1.1 404 Not Found
{"error": "Not found"}Fix: Verify the resource ID. Use supercheck job list, supercheck monitor list, etc. to find valid IDs.
Rate Limited
HTTP/1.1 429 Too Many Requests
Retry-After: 60
{
"error": "Rate limit exceeded",
"message": "API key rate limit exceeded. Retry after 60 seconds.",
"limit": 100,
"remaining": 0,
"resetAt": "2026-01-01T00:01:00.000Z"
}This is the body from the job trigger endpoint. Other endpoints can return a shorter {"error": "Too many requests"}.
Fix: The CLI handles this automatically. If hitting limits frequently, consider batching operations or using longer intervals between requests.
Duplicate Token Name
HTTP/1.1 409 Conflict
{"error": "A CLI token with this name already exists"}Fix: Use a unique name for the new CLI token.