---
title: "Errors & responses"
description: "Response envelopes, error codes, and HTTP status mapping."
canonical: https://bennybooks.com/developers/errors
markdown: https://bennybooks.com/developers/errors.md
---
# Errors & responses

Response envelopes, error codes, and HTTP status mapping.

> **Documentation index.** Fetch [https://bennybooks.com/developers/llms.txt](https://bennybooks.com/developers/llms.txt) before browsing further. Prefer markdown (this file or `Accept: text/markdown`). Site-wide map: [https://bennybooks.com/llms.txt](https://bennybooks.com/llms.txt).

## Success responses

```json
{
  "data": { },
  "meta": { "totalCount": 42, "limit": 50, "offset": 0 }
}
```

meta is optional — list endpoints include pagination; write endpoints return 201 with the created resource in data.

## Error responses

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": { }
  }
}
```

| HTTP | Code | When |
| --- | --- | --- |
| 400 | VALIDATION_ERROR | Invalid query params or request body |
| 401 | UNAUTHORIZED | Missing or invalid token |
| 403 | FORBIDDEN | Insufficient scope (e.g. read token on write) |
| 404 | NOT_FOUND | Resource not in this organization |
| 500 | INTERNAL_ERROR | Unexpected server error |
| 503 | SERVICE_UNAVAILABLE | Database not configured |

---

## Machine-readable

- HTML: https://bennybooks.com/developers/errors
- Markdown: https://bennybooks.com/developers/errors.md
- Docs index: https://bennybooks.com/developers/llms.txt
- OpenAPI: https://bennybooks.com/openapi.json
- Skill: https://bennybooks.com/skill.md
- Auth: https://bennybooks.com/auth.md

```json
{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "Errors & responses",
  "description": "Response envelopes, error codes, and HTTP status mapping.",
  "url": "https://bennybooks.com/developers/errors",
  "inLanguage": "en",
  "encodingFormat": [
    "text/html",
    "text/markdown"
  ],
  "isAccessibleForFree": true,
  "publisher": {
    "@type": "Organization",
    "name": "BennyBooks",
    "url": "https://bennybooks.com",
    "logo": {
      "@type": "ImageObject",
      "url": "https://bennybooks.com/apple-icon.png"
    }
  },
  "mainEntityOfPage": "https://bennybooks.com/developers/errors",
  "image": "https://bennybooks.com/opengraph-image",
  "workExample": {
    "@type": "CreativeWork",
    "url": "https://bennybooks.com/developers/errors.md",
    "encodingFormat": "text/markdown",
    "name": "Errors & responses (Markdown)"
  },
  "about": {
    "@type": "WebAPI",
    "name": "BennyBooks Agent API",
    "url": "https://bennybooks.com/api/v1",
    "documentation": "https://bennybooks.com/developers"
  }
}
```
