Error Documentation

In this tutorial, you will learn about Error Documentation. We cover key concepts, practical examples, and best practices to help you master this topic.

Error documentation helps developers debug and fix API integration problems by documenting every error code, showing error response formats, explaining what causes each error, and providing step-by-step troubleshooting guidance for every failure case.

What You'll Learn

How to structure error documentation, what information every error entry needs, how to write clear error messages, how to document error causes and solutions, how to use standard error formats like RFC 9457, and how to organize error catalogs for quick lookup.

Why It Matters

Errors are inevitable. Well-documented errors transform frustrating debugging sessions into five-minute fixes. Poorly documented errors generate support tickets, erode developer trust, and make your API seem unreliable even when the errors are the developer's fault.

Real-World Use

Stripe's error documentation lists every possible error code with the HTTP status, what caused the error, and how to fix it. When a DodaTech API integration fails, the response includes a machine-readable code, human-readable message, and a documentation URL linking directly to the relevant error page.

Error Documentation Structure

flowchart TD
  A[Error Documentation] --> B[Error Response Format]
  A --> C[Error Code Catalog]
  A --> D[Troubleshooting Guides]
  C --> E[HTTP Status]
  C --> F[Error Code]
  C --> G[Message]
  C --> H[Cause]
  C --> I[Solution]
  D --> J[Common Scenarios]
  D --> K[Debugging Steps]
  D --> L[Support Resources]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Error Response Format

Document the standard error format so developers know what to expect.

## Error Response Format

All errors follow the RFC 9457 Problem Details format:

```json
{
  "type": "https://docs.dodatech.com/errors/file-too-large",
  "title": "File exceeds size limit",
  "status": 413,
  "detail": "The uploaded file is 750 MB. Maximum file size is 500 MB.",
  "instance": "/v2/files/compress",
  "code": "FILE_TOO_LARGE",
  "docs_url": "https://docs.dodatech.com/errors/file-too-large"
}

## Error Code Catalog

Organize errors by HTTP status code with a table for quick lookup.

```markdown
## Error Code Catalog

### 400 Bad Request

| Code | Message | Cause | Solution |
|------|---------|-------|----------|
| INVALID_FORMAT | Compression format not recognized | format value is not zip, gzip, or sevenz | Use one of the supported values |
| INVALID_PARAMETER | Parameter validation failed | Missing or invalid required parameter | Check parameter types and constraints |
| MALFORMED_REQUEST | Request body is not valid JSON | JSON parse error in request body | Validate JSON before sending |

### 401 Unauthorized

| Code | Message | Cause | Solution |
|------|---------|-------|----------|
| MISSING_API_KEY | No API key provided | Missing Authorization header | Add Bearer token to request |
| INVALID_API_KEY | API key is not valid | Key was revoked or malformed | Generate a new API key |
| EXPIRED_API_KEY | API key has expired | Key is past its expiration date | Rotate to a new key |

### 403 Forbidden

| Code | Message | Cause | Solution |
|------|---------|-------|----------|
| INSUFFICIENT_SCOPE | API key lacks required permission | Key missing required scope | Generate key with appropriate scopes |
| RATE_LIMITED | Too many requests | Exceeded rate limit | Implement exponential backoff |
| QUOTA_EXCEEDED | Monthly quota exhausted | Exceeded plan limit | Upgrade plan or wait for reset |

### 500 Internal Server Error

| Code | Message | Cause | Solution |
|------|---------|-------|----------|
| INTERNAL_ERROR | Unexpected server error | Transient server issue | Retry with exponential backoff |
| SERVICE_UNAVAILABLE | Service temporarily unavailable | Planned maintenance or outage | Check status.dodatech.com |

## Troubleshooting Guides

For common error scenarios, provide step-by-step debugging guides.

```markdown
## Troubleshooting: Rate Limited Errors

If you receive HTTP 429 errors, your application is sending too many
requests. Here is how to fix it:

1. **Check current rate limits**: See the Rate Limiting page for your
   plan's limits.

2. **Implement exponential backoff**: Wait 1 second, then 2, then 4,
   up to a maximum of 60 seconds between retries.

3. **Add retry-after header support**: The response includes a
   `Retry-After` header with the number of seconds to wait.

```python
import time
from dodatech import RateLimitError

def api_call_with_retry(client, endpoint, **kwargs):
    max_retries = 5
    for attempt in range(max_retries):
        try:
            return client.request(endpoint, **kwargs)
        except RateLimitError as e:
            wait = e.retry_after or (2 ** attempt)
            time.sleep(wait)
    raise Exception("Max retries exceeded")

## Error Prevention in Client Code

Show developers how to handle errors programmatically in their SDK of choice.

```python
from dodatech import Client, AuthenticationError, RateLimitError

client = Client(api_key="YOUR_KEY")

try:
    files = client.files.list()
except AuthenticationError:
    print("Check your API key. Generate a new one from the dashboard.")
except RateLimitError:
    print("Rate limited. Implement exponential backoff.")
except Exception as e:
    print(f"Unexpected error: {e}")
    print(f"Error code: {e.code}")
    print(f"See: {e.docs_url}")

Common Mistakes

1. No Error Documentation

Listing only successful responses without any error documentation forces developers to discover errors through trial and error.

2. Generic Error Messages

Returning Internal server error with no detail forces developers to contact support. Every error needs a specific message and cause.

3. No Machine-Readable Codes

Error messages without codes force developers to parse human text. Always include a machine-readable error code field.

4. Not Documenting Error Response Format

Showing error examples in a different format than the actual API returns causes confusion. Document the exact error schema.

5. No Documentation URLs

Errors without links to documentation force developers to search for solutions. Include a docs_url field in every error response.

6. Incomplete Error Table

Documenting only 4xx errors without 5xx errors leaves developers unprepared for server-side failures.

7. No Troubleshooting Steps

Error codes without specific solutions force developers to guess how to fix the problem. Every error entry needs a cause and solution.

Practice Questions

1. What information should every error documentation entry include?

HTTP status code, machine-readable error code, human-readable message, cause of the error, and step-by-step solution.

2. Why use the RFC 9457 Problem Details format?

RFC 9457 provides a standardized error response format with type, title, status, detail, instance, and code fields that both humans and machines can parse.

3. How does error documentation reduce support tickets?

When developers can look up error codes with causes and solutions, they fix problems themselves instead of contacting support. This reduces support volume significantly.

4. What is the difference between 4xx and 5xx errors?

4xx errors indicate client-side problems (bad request, unauthorized) that the developer can fix. 5xx errors indicate server-side problems that the API provider must fix.

5. Challenge: Document all possible errors for a single API endpoint. Include the error response format, an error code catalog table, and troubleshooting steps for each error code.

FAQ

Mini Project: Build an Error Catalog

Create a complete error catalog for a fictional API with at least 15 error codes across 4 HTTP status categories. Include the error response format, a table per status code with code, message, cause, and solution columns, and a troubleshooting guide for the three most common errors.

What's Next

Errors help developers debug. Now learn to prevent abuse with clear Rate Limiting Documentation. Then explore Endpoint Documentation for documenting specific API operations.