Error Codes

Complete reference of 9 error codes returned by the Status Service.

Error response formatjson

{
  "data": null,
  "error": {
    "code": "ERR_STATUS_NOT_FOUND",
    "message": "Incident not found",
    "http": 404
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "service": "status-svc",
    "timestamp": "2026-02-24T12:00:00.000Z"
  }
}

Code	HTTP	Description	Resolution
`ERR_STATUS_BAD_REQUEST`	400	The request body or query parameters are malformed or invalid	Check request body against API docs. Verify field types and constraints.
`ERR_STATUS_UNAUTHORIZED`	401	Missing or invalid authentication token	Provide a valid JWT token in the Authorization header. Obtain a fresh token from auth-svc.
`ERR_STATUS_FORBIDDEN`	403	Insufficient permissions for this operation	Verify your JWT contains the required role (PLATFORM_OPS, DATA_PROTECTION_OFFICER) or subscription tier.
`ERR_STATUS_NOT_FOUND`	404	The requested resource (incident, maintenance window, service, subscription) was not found	Verify the resource ID exists. For public endpoints, ensure the resource has isPublic=true.
`ERR_STATUS_CONFLICT`	409	Resource conflict: duplicate idempotency key, invalid status transition, or duplicate subscription	For idempotency conflicts, use a new key. For status transitions, follow the state machine: INVESTIGATING -> IDENTIFIED -> MONITORING -> RESOLVED.
`ERR_STATUS_VALIDATION`	422	Request validation failed on one or more fields	Review the validation errors in the response. Fix field values to match constraints (type, min/max, enum values).
`ERR_STATUS_RATE_LIMITED`	429	Rate limit exceeded for this endpoint	Wait and retry after the Retry-After header value. Implement exponential backoff in your client.
`ERR_STATUS_INTERNAL`	500	Internal server error in the status service	Retry the request. If persistent, contact support with the request_id from the response meta.
`ERR_STATUS_DOWNSTREAM_FAILURE`	502	A downstream service (notify-svc, llm-orch-svc, wallet-svc) failed to respond	Retry with exponential backoff. The downstream service may be temporarily unavailable or scaling up.

Status Transition State Machine

Incident status transitions must follow this state machine. Invalid transitions return ERR_STATUS_CONFLICT (409).

Valid status transitionstext

INVESTIGATING -> IDENTIFIED -> MONITORING -> RESOLVED
                                      \-> MONITORING -> RESOLVED
INVESTIGATING -> IDENTIFIED -> RESOLVED  (skip monitoring)
INVESTIGATING -> RESOLVED                (quick resolution)

Idempotency Conflicts

Write operations (POST, PUT, PATCH, DELETE) require an X-Idempotency-Key header. Reusing a key within 24 hours returns the original response. Using a key that was previously used with different request data returns ERR_STATUS_CONFLICT (409).