Response Examples — Complete Guide

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

Response examples show developers the exact data an API endpoint returns including all fields with proper types and realistic values, nested objects, arrays, pagination metadata, and response headers so developers can build parsers that handle every field correctly.

What You'll Learn

How to write response examples that developers can use to build parsers, how to show success and error responses, how to document nested response objects and arrays, how to show paginated responses, and how to include response headers alongside the body.

Why It Matters

Developers build their code around your response format. If the response documentation is wrong, their parsers break. Complete, accurate response examples with all fields prevent null pointer exceptions and Parsing errors in production.

Real-World Use

The DodaTech API response documentation shows every field with type and example, including fields that may be null. When a field can be null, the example shows it as null so developers remember to handle that case in their code.

Response Example Structure

flowchart TD
  A[Response Example] --> B[Status Code]
  A --> C[Headers]
  A --> D[Body]
  D --> E[Primitive Fields]
  D --> F[Nested Objects]
  D --> G[Arrays]
  D --> H[Null Values]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Success Response Examples

Show the complete response body with realistic data for every field.

#### 200 Response: Compression Complete

```json
{
  "job_id": "c7f3a2b1-8d4e-4f5a-9b6c-1d2e3f4a5b6c",
  "status": "completed",
  "input_size": 1048576,
  "output_size": 258432,
  "ratio": 0.246,
  "download_url": "https://api.dodatech.com/v2/download/c7f3a2b1",
  "error": null,
  "created_at": "2026-06-28T10:30:00Z",
  "completed_at": "2026-06-28T10:30:45Z"
}

#### Response Headers

X-Request-ID: a1b2c3d4-e5f6-4a5b-9c8d-7e6f5a4b3c2d
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 842
X-RateLimit-Reset: 1759123456

## Async Response Examples

Show the response for async operations that return a job ID.

```markdown
#### 202 Response: Async Processing Started

```json
{
  "job_id": "c7f3a2b1-8d4e-4f5a-9b6c-1d2e3f4a5b6c",
  "status": "pending",
  "input_size": 524288000,
  "output_size": null,
  "ratio": null,
  "download_url": null,
  "error": null,
  "created_at": "2026-06-28T10:30:00Z",
  "completed_at": null
}

The output_size, ratio, download_url, and completed_at fields are null until the job completes. Poll GET /v2/jobs/{jobId} until status is completed or failed.

Paginated Response Examples

Show the pagination structure for list endpoints.

#### 200 Response: List Files

```json
{
  "data": [
    {
      "id": "file_a1b2c3d4e5f6g7h8",
      "name": "report.pdf",
      "size_bytes": 1048576,
      "format": "pdf",
      "status": "active",
      "created_at": "2026-06-28T10:30:00Z",
      "updated_at": "2026-06-28T10:30:45Z"
    },
    {
      "id": "file_i9j0k1l2m3n4o5p6",
      "name": "data.csv",
      "size_bytes": 256000,
      "format": "csv",
      "status": "active",
      "created_at": "2026-06-27T09:00:00Z",
      "updated_at": "2026-06-27T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 142,
    "total_pages": 8
  }
}

## Error Response Examples

Show the exact response format for each error status code.

```json
// 400 Bad Request
{
  "error": {
    "code": "INVALID_FORMAT",
    "message": "Compression format 'lz4' is not supported.",
    "supported_formats": ["zip", "gzip", "sevenz"],
    "docs_url": "https://docs.dodatech.com/errors/invalid-format"
  }
}

// 401 Unauthorized
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key.",
    "docs_url": "https://docs.dodatech.com/api/auth"
  }
}

// 429 Rate Limited
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Retry after 37 seconds.",
    "retry_after": 37,
    "limit": 1000,
    "remaining": 0
  }
}

Nullable Fields

Document which fields can be null and under what conditions.

#### Nullable Fields

| Field | Null When |
|-------|-----------|
| `output_size` | Job is not yet completed or failed |
| `ratio` | Job is not yet completed |
| `download_url` | Job is not yet completed |
| `error` | Job completed successfully |
| `completed_at` | Job is not yet completed |

Always check for null before accessing these fields to avoid null
pointer exceptions in your code.

## Common Mistakes

### 1. No Error Response Examples

Showing only success responses. Developers need to see error response formats to build proper error handling.

### 2. Unrealistic Example Data

Using placeholder values like string or 0 instead of realistic data. Examples should reflect actual API output.

### 3. Missing Null Fields

Omitting fields that can be null from the example. Developers assume the field is always present and get null pointer exceptions.

### 4. No Response Headers

Documenting only the response body without important response headers like rate limits and request IDs.

### 5. Single Status Code Example

Showing only 200 responses without 201, 202, or error status codes. Every possible response needs an example.

### 6. Inconsistent Data Between Request and Response

Request example sends file_url and response shows different data. Keep request and response examples consistent.

### 7. No Array Structure Examples

Showing arrays with one item can mislead developers about whether the field is always an array. Show arrays with multiple items.

## Practice Questions

**1. What should every response example include?**

Status code, response headers, complete response body with all fields, realistic example data, and proper handling of null values.

**2. Why include error response examples?**

Error response examples show developers the format they should parse when things go wrong. Without error examples, developers build error handling for formats they guess at.

**3. How do you document nullable fields?**

Show the field as null in the example when it would be null in that state. Document the conditions under which each field is null in a separate table.

**4. Why show response headers in examples?**

Response headers carry important information like rate limits, request IDs for tracing, and content type. Developers need to know what headers to expect.

**5. Challenge:** Write response examples for an API endpoint that has three different status codes (200 success, 202 async, and one error). Include headers, full body, and nullable fields for each response.

## 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 response examples should I show per endpoint?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>At least two: the primary success response and the most common error response. For async endpoints, also show the 202 accepted response.</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 response examples show real data?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>Yes, but anonymized. Use realistic but non-identifying data. Never include actual customer data or secrets in documentation examples.</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 responses with dynamic field names?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>Show an example with representative dynamic keys. Use additionalProperties in the schema to indicate that arbitrary keys are allowed.</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 if a field can be multiple types?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>Show examples of both types. For example, show the field as a string in one example and as null in another. Document the conditions for each type.</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 handle very large response examples?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>Show a truncated example with the full structure but abbreviated data. Note where the pattern repeats. Link to the full schema for complete reference.</p>
</div></details>

## Mini Project: Write Response Documentation

Pick an API endpoint with a complex response including nested objects, arrays, nullable fields, and multiple status codes. Write complete response documentation with examples for each status code, response headers, a nullable fields table, and language-specific parsing examples.

## What's Next

Good response examples help developers build parsers. Now learn to document failures with Writing Error Descriptions. Then explore Authentication Documentation.