Errors & conventions

Conventions

• Content type — send Content-Type: application/json on POST and PATCH.
• Responses — JSON. A successful call returns the resource, or { "message": "..." }.

Error envelopes

There are two error shapes.

Shape validation (Joi) → 422

Request-shape errors return an error array. Each entry's path points at the exact offending field, so a caller (or agent) can correct itself.

{
  "error": [
    {
      "message": "\"values\" must contain at least 1 items",
      "path": ["channels", "FB_PAGE_123", "superpower", "conditionGroups", 0, "conditions", 0, "values"],
      "type": "array.min",
      "context": {}
    }
  ]
}

Business errors → 400 / 409 / 422

Model and business-rule errors return a message (plus optional details).

{ "message": "Hashtag already in use" }

Status codes