#pragma once // OpenRouter error semantics (https://openrouter.ai/docs/api-reference/errors). // Envelope: {"error":{"code":402,"message":"...","metadata":{...}}} with a // NUMERIC code. Provider errors add metadata.error_type (a stable typed // vocabulary), provider_code, raw, provider_name. A 200 response can still // carry an error: a mid-stream error arrives as an SSE chunk with a top-level // `error` and finish_reason "error"; a non-streaming provider failure arrives // as a 200 JSON body holding only `error`. Both are mapped to llm::ApiError // here so callers have one failure path. #include #include "clients/body/json.h" #include "llm/error.h" namespace molo::openrouter { enum class FailureKind { kInvalidRequest, // 400, 413, 422 kUnauthorized, // 401 kCredits, // 402 insufficient credits (or an in-flight budget) kForbidden, // 403 guardrail, moderation, budget, permission kNotFound, // 404 kTimeout, // 408, 504, 524 kRateLimited, // 429 kProviderFailed, // 502 model down or invalid provider response kNoProvider, // 503 no provider meets the routing requirements kOverloaded, // 529 kServer, // other 5xx kOther, }; const char* failure_kind_name(FailureKind kind); FailureKind classify_status(int http_status); // True when waiting and retrying can help (408, 429, 502, 503, 504, 524, 529). bool failure_retryable(FailureKind kind); struct ErrorInfo { FailureKind kind = FailureKind::kOther; bool retryable = false; std::string hint; // One line for people reading logs. }; // Never throws. Based on the status and the vendor type string only (the // foundation ApiError does not carry the error metadata or Retry-After). ErrorInfo describe(const llm::ApiError& error); // The typed error_type vocabulary from the docs (metadata.error_type). bool is_known_error_type(const std::string& type); // HTTP status the docs assign to an error_type, 0 when unknown. int status_for_error_type(const std::string& type); // The `error` object of a chunk or body. struct ErrorBody { int code = 0; std::string message; std::string error_type; // metadata.error_type std::string provider_code; // metadata.provider_code std::string provider_name; // metadata.provider_name clients::body::Json metadata; static ErrorBody parse(const clients::body::Json& error_object); // vendor "openrouter"; type is error_type when present, else the code. llm::ApiError to_api_error() const; }; // Throws when `doc` is a JSON object with a top-level `error` object (the // 200-with-error shapes). Does nothing otherwise. void throw_if_error_body(const clients::body::Json& doc); } // namespace molo::openrouter