---
title: Errors & status codes
description: HTTP status codes and JSON error shapes returned by the Schedule & Chill API.
published: 2026-06-07
updated: 2026-09-14
---

# Errors & status codes
The API uses conventional HTTP status codes and returns JSON error bodies. Always send `Accept: application/json` so errors come back as JSON.

## Status codes

| Code                       | Meaning                                                                         |
| -------------------------- | ------------------------------------------------------------------------------- |
| `200 OK`                   | Successful `GET` or `PUT`.                                                      |
| `201 Created`              | Resource created (`POST`).                                                      |
| `204 No Content`           | Successful `DELETE`.                                                            |
| `401 Unauthorized`         | Missing or invalid API key.                                                     |
| `403 Forbidden`            | Authenticated, but not allowed to access this resource.                         |
| `404 Not Found`            | Resource does not exist.                                                        |
| `422 Unprocessable Entity` | Validation failed, or the action isn't allowed in the resource's current state. |

## Validation errors

A `422` returns a `message` and a field-keyed `errors` object:

```json
{
    "message": "The content field is required.",
    "errors": {
        "content": ["The content field is required."],
        "scheduled_at": ["The scheduled at must be a date after now."]
    }
}
```

## State errors

Some actions are only valid in certain states — for example, only `draft` and `scheduled` posts can be updated. These also return `422` with a plain `message`:

```json
{ "message": "Only draft and scheduled posts can be updated" }
```

## Handling errors

- Treat any `4xx` as a client-side issue to fix (bad input, wrong id, missing auth).
- Inspect `errors` to surface field-level messages to your users.
- Retry only on `5xx` / network failures, with backoff.