Writing Error Descriptions

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

Error descriptions help developers understand why an API request failed and how to fix it by providing clear error messages, documented causes, step-by-step troubleshooting guidance, and machine-readable error codes that map to specific failure scenarios.

What You'll Learn

How to write clear error messages, how to document error causes and solutions, how to structure an error catalog, how to use RFC 9457 Problem Details format, and how to write troubleshooting guides for common error scenarios.

Why It Matters

Poor error messages are the number one cause of API support tickets. A vague error like Internal server error forces developers to contact support. A specific error like File exceeds the 500 MB limit with a link to the troubleshooting guide resolves the issue immediately without human intervention.

Real-World Use

The DodaTech API returns errors in RFC 9457 format with a code, message, detail, and docs_url. Every error links to a documentation page with the cause, solution, and code examples. This reduced error-related support tickets by 70 percent.

Error Message Anatomy

flowchart TD
  A[Error Response] --> B[HTTP Status]
  A --> C[Error Code]
  A --> D[Message]
  A --> E[Detail]
  A --> F[docs_url]
  B --> G[4xx Client / 5xx Server]
  C --> H[Machine-readable]
  D --> I[Human-readable summary]
  E --> J[Specific values that caused error]
  F --> K[Link to troubleshooting]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Writing Clear Error Messages

Every error message should tell the developer what went wrong, why it went wrong, and what to do about it.

// Good: specific error with all three elements
{
  "code": "FILE_TOO_LARGE",
  "message": "File exceeds the maximum size limit.",
  "detail": "The uploaded file 'report.mp4' is 750 MB. Maximum file size is 500 MB.",
  "docs_url": "https://docs.dodatech.com/errors/file-too-large",
  "status": 413
}

// Bad: vague error with no actionable information
{
  "code": "ERROR",
  "message": "Something went wrong.",
  "status": 500
}

Error Code Catalog Structure

Organize error codes by category for quick reference.

## Error Code Catalog

### 400 Bad Request

| Code | Message | Cause | Solution |
|------|---------|-------|----------|
| INVALID_FORMAT | Compression format not recognized | The format parameter value is not one of the supported values | Use one of: zip, gzip, sevenz. Check for typos |
| INVALID_PARAMETER | Parameter validation failed | A required parameter is missing or has an invalid value | Check the parameter type, format, and constraints |
| MALFORMED_REQUEST | Request body is not valid JSON | The request body could not be parsed as JSON | Validate your JSON before sending. Use a JSON linter |

### 401 Unauthorized

| Code | Message | Cause | Solution |
|------|---------|-------|----------|
| MISSING_API_KEY | No API key provided | The Authorization header is missing | Add Authorization: Bearer YOUR_KEY to your request |
| INVALID_API_KEY | API key is not valid | The key was revoked, expired, or malformed | Generate a new API key from the dashboard |

### 429 Rate Limited

| Code | Message | Cause | Solution |
|------|---------|-------|----------|
| RATE_LIMITED | Too many requests | You have exceeded the rate limit for your plan | Wait for the Retry-After duration and implement exponential backoff |
| QUOTA_EXCEEDED | Monthly quota exhausted | You have used all requests for this billing period | Upgrade your plan or wait for the quota reset |

## Troubleshooting Guides

For complex errors, provide step-by-step debugging guidance.

```markdown
## Troubleshooting: Compression Job Fails

If your compression job completes with status: failed, follow these
steps to diagnose the issue:

### Step 1: Check the Error Field

```json
{
  "status": "failed",
  "error": {
    "code": "CORRUPTED_FILE",
    "message": "The source file appears to be corrupted or truncated.",
    "detail": "File size mismatch: expected 1048576 bytes, received 982365 bytes."
  }
}

Step 2: Verify Source File Integrity

# Check file checksum
sha256sum report.pdf

# Compare with original checksum
# If checksums don't match, re-upload the file

Step 3: Check File Format

Ensure the file is in a supported format and not password-protected before compression. Durga Antivirus Pro can verify file integrity before submission.

Error Prevention in Documentation

Teach developers to avoid errors before they happen.

## Preventing Common Errors

### File Size Limits

Check the file size before uploading to avoid 413 errors:

```python
file_size = os.path.getsize("report.mp4")
max_size = 500 * 1024 * 1024  # 500 MB

if file_size > max_size:
    print(f"File too large: {file_size / 1024 / 1024:.1f} MB")
    print(f"Maximum size: {max_size / 1024 / 1024:.0f} MB")
    print("Split the file into smaller parts.")

Rate Limits

Check remaining requests before making API calls:

response = client.files.list()
remaining = response.headers["X-RateLimit-Remaining"]
reset_time = response.headers["X-RateLimit-Reset"]

if int(remaining) < 10:
    print(f"Only {remaining} requests remaining. Queue requests.")

## Common Mistakes

### 1. Generic Error Messages

Writing error without specific detail. Every error message should include specific values that caused the error, not just a generic description.

### 2. No Machine-Readable Code

Error responses without a code field force developers to parse human-readable text to determine the error type programmatically.

### 3. No Documentation Link

Errors without a docs_url force developers to search for solutions. Every error should link directly to the relevant troubleshooting page.

### 4. Missing Detail Field

Error responses without a detail field lack the specific values that would help developers debug the issue immediately.

### 5. Inconsistent Error Format

Different endpoints returning errors in different formats. Standardize on one format (RFC 9457) across the entire API.

### 6. No Troubleshooting Guides

Error code catalogs without step-by-step troubleshooting guides leave developers without clear repair instructions.

### 7. Not Teaching Prevention

Documenting error codes without showing developers how to prevent them in the first place. Prevention examples reduce error rates.

## Practice Questions

**1. What three pieces of information should every error message include?**

What went wrong (clear message), why it went wrong (cause with specific values), and how to fix it (solution with actionable steps).

**2. What is RFC 9457 Problem Details format?**

A standardized error response format with type (URI to docs), title (short summary), status (HTTP code), detail (specific explanation), and instance (endpoint that generated the error).

**3. Why include a docs_url in every error response?**

The docs_url links directly to the troubleshooting page for that specific error. Developers can click the link and get step-by-step resolution instructions immediately.

**4. What is the difference between a 4xx and 5xx error?**

4xx errors mean the developer sent something wrong (bad request, unauthorized). 5xx errors mean the API server has a problem. Document retry strategies for 5xx errors.

**5. Challenge:** Write error documentation for an API endpoint that can return at least 5 different error codes. Include the error response format, a table with all error codes, and troubleshooting guides for the three most common errors.

## FAQ

<details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">How many error codes should an API have?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>Enough to distinguish every unique failure case, but not so many that developers cannot remember them. 10-30 error codes is typical for most APIs. Group related failures under the same code with different detail messages.</p>
</div></details>

<details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">Should error messages include dynamic values like file names?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>Yes. Specific values help developers identify exactly what caused the error. Instead of File too large, say The file report.mp4 is 750 MB. Maximum is 500 MB.</p>
</div></details>

<details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">What is the difference between error code and error message?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>The error code is a machine-readable string (FILE_TOO_LARGE) that the application uses for programmatic handling. The message is a human-readable explanation.</p>
</div></details>

<details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">How do I document errors for async operations?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>Async operations return 202 Accepted initially. Errors appear when the developer polls the job status endpoint. Document both initial validation errors and async processing errors.</p>
</div></details>

<details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">Should I include error examples in the OpenAPI spec?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>Yes. Every response status code should be defined in the OpenAPI spec with a schema and example. Generated documentation will then show error formats alongside success responses.</p>
</div></details>

## Mini Project: Error Documentation Catalog

Create a complete error documentation catalog for an API with at least 15 error codes across 4 HTTP status categories. Include the error response format, a table per status code, troubleshooting guides for the 5 most common errors, and prevention examples in at least one programming language.

## What's Next

Error descriptions help developers fix issues. Now learn to document how developers authenticate with Authentication Documentation. Then explore Rate Limit Documentation.