API Errors

API Errors

This page explains the most common HTTP error codes returned by the Overwatch API, their causes, and how to fix them. Each section includes the error code, typical causes, and step-by-step resolution.

Exploring the API

Before debugging errors, familiarize yourself with the API documentation:

• Interactive docs: Navigate to <your-api-url>/docs in a browser to open the auto-generated OpenAPI (Swagger) interface
• Test endpoints: Use the “Try it out” button in the Swagger UI to send requests directly
• Curl testing: Copy the generated curl command from Swagger to reproduce requests from your terminal

# Basic authenticated request
curl -H "Authorization: Bearer <your-jwt-token>" \
     https://api.your-overwatch-instance.com/api/v1/incidents

Tip: The /docs endpoint is always available and requires no authentication. Use it as a connectivity check when debugging API issues.

401 Unauthorized

Problem: The API rejects your request with 401 Unauthorized.

Cause: The request is missing an authentication header, the JWT token has expired, or the API key is invalid.

Solution:

1. Verify the Authorization header is present and formatted as Bearer <token>
2. Check whether your JWT has expired --- tokens have a limited lifetime and must be refreshed
3. If using an API key, confirm the key is correct and has not been revoked in Settings > API Keys
4. Re-authenticate by logging in again to obtain a fresh token

# Verify your token is being sent correctly
curl -v -H "Authorization: Bearer <token>" \
     https://api.your-overwatch-instance.com/api/v1/users/me

403 Forbidden

Problem: The API returns 403 Forbidden even though you are authenticated.

Cause: Your user role does not have permission for the requested action, or you are attempting to access a resource belonging to a different organization.

Solution:

1. Check your assigned role in Settings > Organization > Members --- Viewer, Engineer, Manager, and Admin roles have different permission levels
2. Verify the resource belongs to your organization --- cross-organization access is blocked by design
3. Contact your organization admin to request a role upgrade if you need additional permissions
4. Review the Roles & Permissions documentation for a breakdown of what each role can do

404 Not Found

Problem: The API returns 404 Not Found for a request you expect to succeed.

Cause: The endpoint URL is incorrect, the resource has been deleted, or the resource ID is wrong.

Solution:

1. Check the endpoint path against the API documentation --- a missing /api/v1/ prefix is a common mistake
2. Verify the resource ID is correct and that the resource has not been deleted
3. Confirm you are using the correct HTTP method (GET, POST, PUT, DELETE) for the endpoint
4. Check for trailing slashes --- some endpoints are sensitive to URL formatting

# Correct endpoint format
curl -H "Authorization: Bearer <token>" \
     https://api.your-overwatch-instance.com/api/v1/incidents/<incident-id>

422 Validation Error

Problem: The API returns 422 Unprocessable Entity with validation error details.

Cause: The request body does not match the expected schema. Common issues include missing required fields, incorrect data types, or values outside allowed ranges.

Solution:

1. Read the error response body --- it includes specific field names and validation messages
2. Compare your request payload against the schema in the API docs at /docs
3. Check for required fields that may be missing from your request
4. Verify data types: strings vs numbers, ISO date formats, valid enum values

{
  "detail": [
    {
      "loc": ["body", "severity"],
      "msg": "value is not a valid enumeration member",
      "type": "type_error.enum"
    }
  ]
}

Note: Severity values must be one of: critical, high, medium, low. Check the schema definitions in the API docs for all valid enum values.

429 Rate Limited

Problem: The API returns 429 Too Many Requests.

Cause: You have exceeded the API rate limit for your account or organization tier.

Solution:

1. Implement exponential backoff in your client code --- wait before retrying, increasing the delay with each attempt
2. Check the Retry-After header in the response for the recommended wait time in seconds
3. Reduce request frequency by batching operations or caching responses client-side
4. If you consistently hit rate limits, contact your admin about upgrading your organization tier

# Check rate limit headers in the response
curl -v -H "Authorization: Bearer <token>" \
     https://api.your-overwatch-instance.com/api/v1/incidents 2>&1 | grep -i "rate\|retry"

500 Internal Server Error

Problem: The API returns 500 Internal Server Error.

Cause: An unhandled exception occurred on the server. This is not caused by your request format but by an internal issue.

Solution:

1. Retry the request after a short delay --- transient errors (database timeouts, temporary resource exhaustion) often resolve on their own
2. If the error persists, note the request URL, method, payload, and timestamp
3. Check the Overwatch status page or contact your administrator to report the issue
4. For self-hosted deployments, check backend logs for the full stack trace:

# Local development
docker compose logs backend -f

# AWS production (CloudWatch)
aws logs tail /ecs/overwatch-backend --follow --profile overwatch-biz

Note: If you can reproduce a 500 error consistently with a specific request, include the full request details when reporting the issue. This significantly speeds up diagnosis.

Debugging Checklist

When troubleshooting any API error, work through this checklist:

1. Check connectivity: Can you reach <your-api-url>/docs in a browser?
2. Check authentication: Is your token valid and included in the request?
3. Check the endpoint: Does the URL match the API docs exactly?
4. Check the payload: Does your request body match the expected schema?
5. Check permissions: Does your role allow the requested action?
6. Check logs: What does the browser console or server log show?

If you have worked through this checklist and the issue persists, contact support at support@overwatch-observability.com with the error code, request details, and any log output.