papers/hanzo-api-gateway/sections/06-error-handling.tex

\section{Error Handling}


\subsection{Error Response Format}

\begin{lstlisting}[language=json, caption=Error Response]
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "The price must be a positive number",
    "param": "price",
    "doc_url": "https://docs.hanzo.ai/errors#parameter_invalid"
  },
  "request_id": "req_abc123"
}
\end{lstlisting}

\subsection{Error Categories}

\begin{table}[h]
\centering
\caption{Error Types}
\begin{tabular}{lll}
\toprule
\textbf{Type} & \textbf{HTTP Status} & \textbf{Description} \\
\midrule
invalid\_request\_error & 400 & Malformed request \\
authentication\_error & 401 & Invalid credentials \\
authorization\_error & 403 & Insufficient permissions \\
not\_found\_error & 404 & Resource not found \\
rate\_limit\_error & 429 & Quota exceeded \\
api\_error & 500 & Internal error \\
\bottomrule
\end{tabular}
\end{table}

\subsection{Idempotency}

Write operations support idempotency keys:

\begin{lstlisting}[caption=Idempotent Request]
POST /v1/orders
Idempotency-Key: order_123_attempt_1
Content-Type: application/json

{"items": [...], "customer": "cus_abc"}
\end{lstlisting}

\begin{algorithm}
\caption{Idempotent Request Processing}
\begin{algorithmic}[1]
\Function{ProcessIdempotent}{$request$}
    \State $key \gets request.headers[IdempotencyKey]$
    \If{$key \neq \bot$}
        \State $cached \gets$ \Call{GetIdempotencyCache}{$key$}
        \If{$cached \neq \bot$}
            \If{$cached.requestHash = hash(request.body)$}
                \State \Return $cached.response$
            \Else
                \State \Return \textsc{IdempotencyKeyReused}
            \EndIf
        \EndIf
    \EndIf
    \State $response \gets$ \Call{ProcessRequest}{$request$}
    \If{$key \neq \bot$}
        \State \Call{SetIdempotencyCache}{$key$, $hash(request.body)$, $response$}
    \EndIf
    \State \Return $response$
\EndFunction
\end{algorithmic}
\end{algorithm}