Error Codes

Error Response Format

All error responses follow a consistent JSON structure:

{
  "code": "ERROR_CODE",
  "message": "Human-readable description of what went wrong.",
  "details": {}
}

Field	Type	Description
code	string	Machine-readable error code (e.g., NOT_FOUND, VALIDATION_ERROR)
message	string	Human-readable explanation
details	object	Optional additional context (varies by error type)

HTTP Status Codes

400 Bad Request

The request is malformed or contains invalid parameters.

{
  "code": "INVALID_STATUS_TRANSITION",
  "message": "Cannot transition from 'suggested' to 'implemented'. Valid transitions: accepted, rejected."
}

401 Unauthorized

Missing or invalid authentication token.

{
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired authentication token."
}

402 Payment Required

Usage limit exceeded for the current plan.

{
  "code": "USAGE_LIMIT_EXCEEDED",
  "message": "Synthesis limit reached for your plan.",
  "details": {
    "usage_type": "synthesis",
    "current": 3,
    "limit": 3,
    "plan": "trial",
    "upgrade_required": true
  }
}

403 Forbidden

The authenticated user does not have permission for this action.

{
  "code": "FORBIDDEN",
  "message": "You do not have access to this workspace"
}

404 Not Found

The requested resource does not exist.

{
  "code": "NOT_FOUND",
  "message": "Workspace 550e8400-e29b-41d4-a716-446655440000 not found"
}

409 Conflict

A conflicting operation is already in progress.

{
  "code": "SYNTHESIS_IN_PROGRESS",
  "message": "Synthesis is already running for this workspace. Please wait."
}

413 Payload Too Large

Uploaded file exceeds the size limit (100 MB).

{
  "code": "FILE_TOO_LARGE",
  "message": "File size (150 MB) exceeds 100 MB limit"
}

415 Unsupported Media Type

Uploaded file type is not allowed (executables, scripts).

{
  "code": "UNSUPPORTED_FILE_TYPE",
  "message": "Executable and script files are not allowed."
}

422 Unprocessable Entity

The request is well-formed but contains semantic errors.

{
  "code": "SOURCES_NOT_READY",
  "message": "2 source(s) are not yet processed: User Interviews, Support Logs. Wait for processing to complete before synthesizing."
}

429 Too Many Requests

Rate limit exceeded.

{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded. Retry after 12 seconds.",
  "details": {
    "retry_after": 12
  }
}

500 Internal Server Error

An unexpected error occurred on the server.

{
  "code": "SYNTHESIS_FAILED",
  "message": "Synthesis failed: Agent timed out after 300 seconds."
}

502 Bad Gateway

An upstream service (Stripe, GitHub, Linear) returned an error.

{
  "code": "BAD_GATEWAY",
  "message": "Failed to create Stripe customer"
}

503 Service Unavailable

A required service is not configured or unavailable.

{
  "code": "AGENT_NOT_CONFIGURED",
  "message": "AI agent is not configured. Please check ANTHROPIC_API_KEY."
}