Error Codes

All Claw GRC API errors follow a consistent JSON format:

{
  "error": "error_type",
  "message": "Human-readable description of what went wrong",
  "details": {}
}

HTTP Status Codes

400 Bad Request

The request body or parameters are malformed or missing required fields.

{
  "error": "bad_request",
  "message": "Missing required field: title"
}

Common causes:

• Missing required fields in the request body
• Invalid field values (e.g., a string where a UUID is expected)
• Malformed JSON in the request body
• Invalid query parameter values

401 Unauthorized

Authentication failed or no credentials were provided.

{
  "error": "unauthorized",
  "message": "Invalid or expired authentication token"
}

Common causes:

• Missing Authorization or X-API-Key header
• Expired JWT token (tokens expire after 1 hour)
• Invalid API key (key does not exist or has been rotated)
• Malformed Bearer token

Resolution: Refresh your JWT token or verify your API key is correct. If the key was rotated, use the new key.

403 Forbidden

The authenticated user/agent does not have permission for this action.

{
  "error": "forbidden",
  "message": "Insufficient permissions for this operation"
}

Common causes:

• Agent trying to invoke a tool not in its capabilities list
• User with auditor role trying to modify data
• Agent-to-agent invocation where the target's trust score is too low
• Cross-session access attempt (trying to use another actor's MCP session)

404 Not Found

The requested resource does not exist or is not accessible to the authenticated organization.

{
  "error": "not_found",
  "message": "Framework 550e8400-... not found"
}

Common causes:

• Invalid resource UUID
• Resource belongs to a different organization (RLS prevents access)
• Resource has been deleted
• Expired or closed MCP session

409 Conflict

The request conflicts with the current state of a resource.

{
  "error": "conflict",
  "message": "Cannot rotate key for an inactive agent"
}

Common causes:

• Trying to rotate an API key for an inactive agent
• Trying to invoke an inactive agent
• Duplicate resource creation (e.g., duplicate control mapping)

413 Request Entity Too Large

The request payload exceeds size limits.

{
  "error": "payload_too_large",
  "message": "Tool params too large (72000 bytes, max 65536)"
}

Common causes:

• MCP message params exceeding the 64KB limit
• File upload exceeding the maximum file size

422 Unprocessable Entity

The request is syntactically valid but semantically incorrect.

{
  "error": "validation_error",
  "message": "Validation failed",
  "details": [
    {
      "field": "severity",
      "message": "Value must be one of: critical, high, medium, low, info"
    }
  ]
}

Common causes:

• Enum value not in the allowed set (e.g., invalid severity level)
• Target agent lacks a required capability
• Value out of allowed range (e.g., CVSS score above 10.0)

429 Too Many Requests

Rate limit exceeded.

{
  "error": "rate_limited",
  "message": "Rate limit exceeded. Retry after 30 seconds."
}

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705312830
Retry-After: 30

Resolution: Wait for the Retry-After duration before retrying. Implement exponential backoff in your client.

500 Internal Server Error

An unexpected error occurred on the server.

{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again."
}

Resolution: Retry the request. If the error persists, contact support@clawgrc.com with the request ID from the response headers.

502 Bad Gateway

A downstream service returned an invalid response.

{
  "status": "Bad Gateway",
  "message": "upstream service returned an invalid response"
}

Resolution: This is a transient error. Retry after a brief delay.

503 Service Unavailable

A downstream service is unreachable or the circuit breaker is open.

{
  "error": "service unavailable"
}

Common causes:

• A backend service (compliance engine, security engine, or agent protocol) is down or restarting
• Circuit breaker opened after multiple consecutive failures
• Service deployment in progress

Resolution: Retry after 10-30 seconds. The circuit breaker will attempt to re-establish connectivity automatically.

504 Gateway Timeout

A downstream service did not respond within the timeout period.

{
  "status": "Gateway Timeout",
  "message": "upstream request timed out"
}

Resolution: The downstream service is running slowly. Retry with a longer timeout or reduce the scope of your request.

Best Practices for Error Handling

1. Always check the status code -- Do not assume success. Check for 2xx status codes before processing the response body.
2. Implement retry logic -- For 429, 500, 502, 503, and 504 errors, implement exponential backoff with jitter.
3. Log error details -- Include the error code, message, and request details in your application logs for debugging.
4. Handle 401 gracefully -- When receiving a 401, refresh your JWT token and retry the request once before failing.
5. Respect rate limits -- Use the X-RateLimit-Remaining header to throttle requests proactively rather than waiting for 429 responses.