API Reference DocumentationLesson 3.3

Documenting API responses and error codes

response schema documentation, HTTP status codes, error response format, error code tables, pagination documentation, partial responses, null vs absent fields

Response and Error Documentation

Response documentation is the most-skipped section in API docs. It shouldn't be. Developers need to know exactly what they get back — field names, types, when fields appear, and what every error means and how to fix it.

Document Every Response Field

**Response (200 OK)**

```json
{
  "id": "string — UUID",
  "email": "string",
  "name": "string",
  "created_at": "string — ISO 8601 datetime",
  "updated_at": "string — ISO 8601 datetime",
  "role": "string — one of: admin, editor, viewer",
  "verified": "boolean — false until email is confirmed"
}
```

Standardize Your Error Format

**Error Response Format**

```json
{
  "error": {
    "code": "INVALID_EMAIL",
    "message": "The email address format is invalid.",
    "field": "email"
  }
}
```

Error Code Table

| Code              | HTTP Status | Cause                          | Fix                                 |
|-------------------|-------------|--------------------------------|-------------------------------------|
| INVALID_EMAIL     | 400         | Email format validation failed | Provide a valid email address       |
| USER_NOT_FOUND    | 404         | No user with given ID          | Verify the user ID exists           |
| RATE_LIMIT        | 429         | Too many requests              | Wait and retry with exponential backoff |

Document null vs absent fields explicitly. Returning null means a field exists but has no value. An absent field means different things in different APIs — document which you use and why.