File size: 2,153 Bytes
f8b48da | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 | <!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Untitled</title>
</head>
<body>
<p>---</p>
<p>doc_id: api-errors</p>
<p>title: API Error Reference</p>
<p>version: 1.0</p>
<p>module: api</p>
<p>last_updated: 2026-09-12</p>
<p>---</p>
<br>
<br>
<h2>Error Response Format (#error-response-format)</h2>
<br>
<p>All errors use a consistent JSON envelope:</p>
<br>
<pre><code>
{
"error": {
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded. Retry after 5 seconds.",
"request_id": "req_9f1c",
"details": {}
}
}
</pre>
<br>
<p>The code field is a stable machine-readable string. The message is human-readable and may change.</p>
<br>
<h2>Error Codes (#error-codes)</h2>
<br>
<table>
<tr><td><b>HTTP</b></td><td><b>Code</b></td><td><b>Common cause</b></td></tr>
<tr><td>400</td><td>invalid_request</td><td>Malformed request body</td></tr>
<tr><td>401</td><td>unauthenticated</td><td>Missing or invalid token</td></tr>
<tr><td>403</td><td>permission_denied</td><td>Token lacks required scope</td></tr>
<tr><td>404</td><td>not_found</td><td>Resource does not exist</td></tr>
<tr><td>409</td><td>conflict</td><td>Resource already exists or state conflict</td></tr>
<tr><td>422</td><td>validation_failed</td><td>Request body failed validation</td></tr>
<tr><td>429</td><td>rate_limit_exceeded</td><td>Too many requests</td></tr>
<tr><td>5xx</td><td>internal_error</td><td>Server-side failure</td></tr>
</table>
<br>
<p>Retryable errors are those in the 5xx range, 429, and 408. Client code should only retry those statuses, with exponential backoff and jitter.</p>
<br>
<h2>Troubleshooting Common Errors (#troubleshooting-common-errors)</h2>
<br>
<p>401 unauthenticated: verify the token is not expired and is sent in the Authorization header.</p>
<br>
<p>403 permission_denied: the token lacks the required scope. Request the scope in the OAuth consent screen.</p>
<br>
<p>429 rate_limit_exceeded: inspect the Retry-After header and back off.</p>
<br>
<p>5xx internal_error: check the status page; retry with exponential backoff.</p>
</body>
</html>
|