Errors

The Controlinfra API uses conventional HTTP status codes and returns structured JSON error responses.

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request — invalid parameters or missing fields
401	Unauthorized — missing or invalid authentication
403	Forbidden — insufficient permissions or scope
404	Not Found — resource does not exist
409	Conflict — resource already exists
429	Too Many Requests — rate limit exceeded
500	Internal Server Error
503	Service Unavailable — rate limiter store down (fail-closed endpoints)

Error Response Format

All errors return a JSON object with a message field:

{
  "message": "No token provided"
}

Some errors include additional context:

{
  "error": "Too many requests",
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests from this IP, please try again later.",
  "retryAfter": 900
}

Authentication Errors

401 — No Token

{
  "message": "No token provided"
}

Ensure the Authorization: Bearer <token> header is present.

401 — Invalid Token

{
  "message": "Invalid token"
}

The token is expired, malformed, or revoked. Obtain a new token.

401 — Invalid CLI Token

{
  "message": "Invalid or expired CLI token"
}

The CLI token has been revoked or does not exist.

401 — Signature Failure

{
  "message": "Request signature verification failed",
  "error": "Request timestamp too old or too far in future",
  "code": "INVALID_SIGNATURE"
}

The CLI request signature is invalid. Check timestamp drift (max 5 minutes) and nonce uniqueness.

Authorization Errors

403 — Insufficient Scope

{
  "message": "Insufficient permissions",
  "error": "This token requires the following scope(s): scans:trigger",
  "requiredScopes": ["scans:trigger"],
  "tokenScopes": ["scans:read"]
}

The CLI token does not have the required scope. Create a new token with the necessary scopes.

403 — Repository Access Denied

{
  "message": "Repository access denied",
  "error": "This token does not have access to this repository"
}

The CLI token is restricted to specific repositories and does not include the requested one.

403 — Admin Required

{
  "message": "Access denied. Admin privileges required."
}

The endpoint requires admin role.

Rate Limiting Errors

429 — Rate Limit Exceeded

{
  "error": "Too many requests",
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests from this IP, please try again later.",
  "retryAfter": 900
}

Wait for retryAfter seconds before retrying. See Rate Limiting for limits per endpoint type.

503 — Service Unavailable

{
  "error": "Service temporarily unavailable",
  "code": "SERVICE_UNAVAILABLE",
  "message": "Rate limiting service is temporarily unavailable. Please try again shortly."
}

Returned by fail-closed rate limiters (auth, credentials) when the Redis store is unavailable.