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:

{
  "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:

{ "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.