1.1 --- a/docs/xen-api/xenapi-datamodel.tex	Thu Dec 21 13:11:24 2006 +0000
     1.2 +++ b/docs/xen-api/xenapi-datamodel.tex	Thu Dec 21 13:12:09 2006 +0000
     1.3 @@ -10428,6 +10428,118 @@ all fields from the object
     1.4  \vspace{0.3cm}
     1.5  
     1.6  \vspace{1cm}
     1.7 +\newpage
     1.8 +\section{Error Handling}
     1.9 +When a low-level transport error occurs, or a request is malformed at the HTTP
    1.10 +or XML-RPC level, the server may send an XML-RPC Fault response, or the client
    1.11 +may simulate the same.  The client must be prepared to handle these errors,
    1.12 +though they may be treated as fatal.  On the wire, these are transmitted in a
    1.13 +form similar to this:
    1.14 +
    1.15 +\begin{verbatim}
    1.16 +    <methodResponse>
    1.17 +      <fault>
    1.18 +        <value>
    1.19 +          <struct>
    1.20 +            <member>
    1.21 +                <name>faultCode</name>
    1.22 +                <value><int>-1</int></value>
    1.23 +              </member>
    1.24 +              <member>
    1.25 +                <name>faultString</name>
    1.26 +                <value><string>Malformed request</string></value>
    1.27 +            </member>
    1.28 +          </struct>
    1.29 +        </value>
    1.30 +      </fault>
    1.31 +    </methodResponse>
    1.32 +\end{verbatim}
    1.33 +
    1.34 +All other failures are reported with a more structured error response, to
    1.35 +allow better automatic response to failures, proper internationalisation of
    1.36 +any error message, and easier debugging.  On the wire, these are transmitted
    1.37 +like this:
    1.38 +
    1.39 +\begin{verbatim}
    1.40 +    <struct>
    1.41 +      <member>
    1.42 +        <name>Status</name>
    1.43 +        <value>Failure</value>
    1.44 +      </member>
    1.45 +      <member>
    1.46 +        <name>ErrorDescription</name>
    1.47 +        <value>
    1.48 +          <array>
    1.49 +            <data>
    1.50 +              <value>MAP_DUPLICATE_KEY</value>
    1.51 +              <value>Customer</value>
    1.52 +              <value>eSpeil Inc.</value>
    1.53 +              <value>eSpeil Incorporated</value>
    1.54 +            </data>
    1.55 +          </array>
    1.56 +        </value>
    1.57 +      </member>
    1.58 +    </struct>
    1.59 +\end{verbatim}
    1.60 +
    1.61 +Note that {\tt ErrorDescription} value is an array of string values. The
    1.62 +first element of the array is an error code; the remainder of the array are
    1.63 +strings representing error parameters relating to that code.  In this case,
    1.64 +the client has attempted to add the mapping {\tt Customer $\rightarrow$
    1.65 +eSpiel Incorporated} to a Map, but it already contains the mapping
    1.66 +{\tt Customer $\rightarrow$ eSpiel Inc.}, and so the request has failed.
    1.67 +
    1.68 +Each possible error code is documented in the following section.
    1.69 +
    1.70 +\subsection{Error Codes}
    1.71 +
    1.72 +\vspace{0.9cm}
    1.73 +\subsubsection{MAP\_DUPLICATE\_KEY}
    1.74 +
    1.75 +You tried to add a key-value pair to a map, but that key is already there. 
    1.76 +The key, current value, and the new value that you tried to set are all
    1.77 +echoed.
    1.78 +
    1.79 +\vspace{0.3cm}
    1.80 +\noindent{\bf Signature:}
    1.81 +\begin{verbatim}MAP_DUPLICATE_KEY(key, current value, new value)\end{verbatim}
    1.82 +
    1.83 +
    1.84 +\vspace{0.9cm}
    1.85 +\subsubsection{INTERNAL\_ERROR}
    1.86 +
    1.87 +The server failed to handle your request, due to an internal error.  The
    1.88 +given message may give details useful for debugging the problem.
    1.89 +
    1.90 +\vspace{0.3cm}
    1.91 +\noindent{\bf Signature:}
    1.92 +\begin{verbatim}INTERNAL_ERROR(message)\end{verbatim}
    1.93 +
    1.94 +
    1.95 +\vspace{0.9cm}
    1.96 +\subsubsection{SESSION\_INVALID}
    1.97 +
    1.98 +You gave an invalid session handle.  It may have been invalidated by a
    1.99 +server restart, or timed out.  You should get a new session handle, using
   1.100 +one of the session.login\_ calls.  This error does not invalidate the
   1.101 +current connection.  The handle parameter echoes the bad value given.
   1.102 +
   1.103 +\vspace{0.3cm}
   1.104 +\noindent{\bf Signature:}
   1.105 +\begin{verbatim}SESSION_INVALID(handle)\end{verbatim}
   1.106 +
   1.107 +
   1.108 +\vspace{0.9cm}
   1.109 +\subsubsection{VM\_HANDLE\_INVALID}
   1.110 +
   1.111 +You gave an invalid VM handle.  The VM may have recently been deleted.  The
   1.112 +handle parameter echoes the bad value given.
   1.113 +
   1.114 +\vspace{0.3cm}
   1.115 +\noindent{\bf Signature:}
   1.116 +\begin{verbatim}VM_HANDLE_INVALID(handle)\end{verbatim}
   1.117 +
   1.118 +\newpage
   1.119  \section{DTD}
   1.120  General notes:
   1.121  \begin{itemize}