Documentation

API Error Codes & Troubleshooting

Complete reference for PolicyCortex API error codes with detailed troubleshooting steps

HTTP Status CodesExamples & SolutionsREST APIError Handling

400

Bad Request

The request is invalid or malformed

⚠️ Common Causes

•Invalid JSON payload in request body
•Missing required parameters
•Invalid parameter values or types
•Malformed API endpoint URL

💻 Examples

Missing required field in policy creation

Request:

POST /api/v1/policies
{
  "name": "Test Policy"
  // Missing "rules" field
}

Response:

{
  "error": "Bad Request",
  "message": "Missing required field: rules",
  "code": 400,
  "details": {
    "field": "rules",
    "type": "required"
  }
}

🔧 Solutions

1Validate request payload against API schema

2Check that all required fields are included

3Verify parameter types match expected values

4Use API documentation to confirm endpoint structure

401

Unauthorized

Authentication failed or missing credentials

⚠️ Common Causes

•Missing or invalid API key
•Expired authentication token
•Incorrect authentication method
•API key not properly formatted in headers

💻 Examples

Missing API key in request headers

Request:

GET /api/v1/policies
// Missing Authorization header

Response:

{
  "error": "Unauthorized",
  "message": "API key required",
  "code": 401
}

Invalid API key format

Request:

GET /api/v1/policies
Authorization: invalid_key_format

Response:

{
  "error": "Unauthorized",
  "message": "Invalid API key format",
  "code": 401,
  "details": {
    "expected_format": "Bearer pc_api_key_..."
  }
}

🔧 Solutions

1Include valid API key in Authorization header

2Use format: "Bearer pc_api_key_..."

3Generate new API key if current one is expired

4Verify API key permissions for the endpoint

403

Forbidden

Valid authentication but insufficient permissions

⚠️ Common Causes

•API key lacks required permissions
•User role restrictions
•Resource-level access controls
•Organization or workspace restrictions

💻 Examples

Insufficient permissions for policy deletion

Request:

DELETE /api/v1/policies/pol_123

Response:

{
  "error": "Forbidden",
  "message": "Insufficient permissions",
  "code": 403,
  "details": {
    "required_permission": "policies:delete",
    "user_permissions": ["policies:read", "policies:write"]
  }
}

🔧 Solutions

1Check user role and permissions

2Request elevated access from administrator

3Use API key with appropriate permissions

4Verify workspace/organization membership

404

Not Found

Requested resource does not exist

⚠️ Common Causes

•Invalid resource ID in URL path
•Resource was deleted or moved
•Incorrect API endpoint URL
•Resource not accessible to current user

💻 Examples

Policy ID does not exist

Request:

GET /api/v1/policies/pol_nonexistent

Response:

{
  "error": "Not Found",
  "message": "Policy not found",
  "code": 404,
  "resource": "policy",
  "id": "pol_nonexistent"
}

🔧 Solutions

1Verify resource ID is correct and exists

2Check if resource was recently deleted

3Confirm API endpoint URL is accurate

4Ensure user has access to the resource

422

Unprocessable Entity

Request is valid but contains semantic errors

⚠️ Common Causes

•Business logic validation failures
•Policy syntax errors
•Conflicting resource states
•Invalid policy rules or conditions

💻 Examples

Invalid policy rule syntax

Request:

POST /api/v1/policies
{
  "name": "Test Policy",
  "rules": [
    {
      "condition": "invalid_syntax_here",
      "action": "deny"
    }
  ]
}

Response:

{
  "error": "Unprocessable Entity",
  "message": "Policy validation failed",
  "code": 422,
  "details": {
    "field": "rules[0].condition",
    "error": "Invalid condition syntax"
  }
}

🔧 Solutions

1Validate policy syntax using schema validator

2Check business logic constraints

3Review policy rule documentation

4Test policy in sandbox environment first

429

Too Many Requests

Rate limit exceeded for API calls

⚠️ Common Causes

•Too many requests in short time period
•Concurrent request limits exceeded
•Bulk operations without rate limiting
•Inefficient API usage patterns

💻 Examples

Rate limit exceeded

Request:

GET /api/v1/policies

Response:

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded",
  "code": 429,
  "details": {
    "limit": 1000,
    "window": "1h",
    "reset_time": "2024-09-15T15:30:00Z"
  }
}

🔧 Solutions

1Implement exponential backoff in API calls

2Reduce request frequency

3Use bulk endpoints where available

4Cache responses to reduce API calls

5Upgrade to higher rate limit tier if needed

500

Internal Server Error

Unexpected server-side error occurred

⚠️ Common Causes

•Temporary service outages
•Database connectivity issues
•Resource processing failures
•Infrastructure problems

💻 Examples

Service temporarily unavailable

Request:

GET /api/v1/scans/scan_123

Response:

{
  "error": "Internal Server Error",
  "message": "Service temporarily unavailable",
  "code": 500,
  "request_id": "req_abc123def456"
}

🔧 Solutions

1Retry request after brief delay

2Check system status page for outages

3Contact support with request ID

4Implement retry logic with exponential backoff

503

Service Unavailable

Service is temporarily overloaded or under maintenance

⚠️ Common Causes

•Scheduled maintenance windows
•High system load
•Service deployment in progress
•Infrastructure scaling events

💻 Examples

Scheduled maintenance

Request:

POST /api/v1/scans

Response:

{
  "error": "Service Unavailable",
  "message": "Service under maintenance",
  "code": 503,
  "retry_after": 3600,
  "maintenance_window": "2024-09-15T02:00:00Z to 2024-09-15T04:00:00Z"
}