Service API Integration · 06
Error Codes
Errors are returned as HTTP status + JSON body (note: not OpenAI's nested {"error": {...}} structure, but FastAPI's {"detail": "..."} format):
json
{ "detail": "Invalid API key" }| Status | detail example | Suggested handling |
|---|---|---|
400 | "No user message found" | No role=user entry in messages array |
400 | "There was an error parsing the body" | Body judged empty / malformed by gateway (common with PowerShell single-quote issues — use -d @body.json instead) |
401 | "Missing API key" / "Invalid API key" | Check Authorization header |
403 | "Service not published" | Service unpublished by admin — contact deployer |
404 | "Conversation not found" | conversation_id doesn't exist or doesn't belong to this service |
422 | [{"type":"json_invalid","loc":["body",N],"msg":"JSON decode error",...}] | Body failed FastAPI validation (valid HTTP but JSON parse / schema mismatch). Note: detail is an array, not a string |
5xx | various | Server-side issue — retry or contact deployer |
400 vs 422: Completely unparseable JSON is usually
422(FastAPI validation); semantically invalid after parsing (e.g. missing user message) is400. Clients should treat both as "request error — don't retry".
Errors during streaming
If an error occurs mid-stream, /chat/completions (OpenAI-compatible) will:
- Append a chunk:
delta.content = "\n\n[Error: <message>]" - Then send
finish_reason: "stop"+data: [DONE] - No HTTP error code (connection already established at 200)
/chat (custom SSE) sends data: {"type": "error", "content": "..."} on error — no done follows. Clients must treat error as a termination signal too.