> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.hive.co/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.hive.co/_mcp/server.

# Errors & Status Codes

The Hive API returns these status codes:

| Code                         | Meaning                                                                                 |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| `200 OK`                     | Request succeeded; the response body contains the requested data                        |
| `201 Created`                | Resource created; the response body contains it                                         |
| `202 Accepted`               | Request received and queued for processing                                              |
| `204 No Content`             | Request succeeded (for example, a delete) with no response body                         |
| `400 Bad Request`            | Malformed request (for example, invalid JSON)                                           |
| `401 Unauthorized`           | Missing or invalid authentication, including expired access tokens                      |
| `403 Forbidden`              | Valid authentication, but not authorized for this resource                              |
| `404 Not Found`              | The resource doesn't exist for the authorized brand                                     |
| `409 Conflict`               | The request conflicts with the resource's current state (for example, a duplicate name) |
| `413 Payload Too Large`      | Request body exceeds 1 MB                                                               |
| `415 Unsupported Media Type` | The request body isn't sent as `application/json`                                       |
| `422 Unprocessable Entity`   | Valid JSON, but fails validation                                                        |
| `429 Too Many Requests`      | Rate limit exceeded. See [Rate Limits](/docs/rate-limits).                              |
| `500 Internal Server Error`  | Unexpected server error. Safe to retry with backoff for idempotent requests             |

## Error response bodies

Error bodies use one of these shapes, depending on the endpoint and error:

| Shape                                                | Returned for                                                                            |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `{"detail": "..."}`                                  | Authentication and permission errors (`401`, `403`), and some `404` and `409` responses |
| `{"errors": ["..."]}`                                | Segment, campaign, and custom event property errors                                     |
| Field-keyed object, for example `{"limit": ["..."]}` | `422` validation errors on single objects and query parameters                          |
| Resource → index → field object (see below)          | `422` validation errors on batch writes                                                 |

Check the HTTP status code first, then read the body for details.

## Validation errors

Batch writes use **all-or-nothing validation**: if any item in a batch is invalid, the whole request is rejected with `422` and nothing is written. Errors are keyed by resource name, then item index, then field path. Fix the failing record and resubmit the full batch.

```json
{
    "orders": {
        "0": {
            "user": { "email": ["Enter a valid email address."] }
        }
    }
}
```

See [How It Works](/docs/how-it-works) for retry guidance.