Error Handling

Enclavely returns a consistent error payload for API/CLI failures.

Error shape

{
  "code": "BAD_REQUEST",
  "message": "request validation failed",
  "status": 400,
  "timestamp": "2026-01-15T10:30:00.000Z",
  "requestId": "req_abc123",
  "path": "/api/trpc/projects.create",
  "details": {
    "issues": [
      {
        "path": "name",
        "message": "expected non-empty value"
      }
    ]
  }
}

Codes

• BAD_REQUEST (400)
• UNAUTHORIZED (401)
• FORBIDDEN (403)
• NOT_FOUND (404)
• CONFLICT (409)
• UNPROCESSABLE_ENTITY (422)
• INTERNAL_SERVER_ERROR (500)

Troubleshooting

UNAUTHORIZED

• Verify API key value and Authorization: Bearer ...
• Re-run enclavely auth login

FORBIDDEN

• Check org role and API key scopes
• Recreate key with required scopes

BAD_REQUEST / UNPROCESSABLE_ENTITY

• Read details.issues for field-level validation failures
• Fix payload/flags and retry

INTERNAL_SERVER_ERROR

• Retry once for transient failures
• Keep requestId for support/debug correlation