Errors

Every response — success or error — uses the same envelope. Read meta.status to branch, meta.code for the machine-readable outcome (it mirrors the HTTP status), and meta.message for a human-readable summary.

The envelope

{
  "meta": {
    "code": 200,
    "status": "success",
    "message": "Product list retrieved successfully."
  },
  "data": { }
}

Field	Type	Description
`meta.code`	integer	Mirrors the HTTP status code.
`meta.status`	string	`"success"` or `"error"`.
`meta.message`	string \| null	Human-readable summary of the outcome.
`data`	object \| array \| null	The payload on success; error details (or `null`) on failure.

There is no top-level errors key

Unlike a default Laravel API, Flavours does not return a top-level errors object. Everything lives under meta and data. On a validation failure the field errors are an array inside data — see below.

HTTP status codes

Status	`meta.status`	When
`200`	`success`	The request succeeded.
`400`	`error`	Malformed request.
`401`	`error`	Missing or invalid credentials.
`403`	`error`	Authenticated, but not allowed to perform this action.
`404`	`error`	The resource (or route) does not exist.
`405`	`error`	The HTTP method is not allowed on this route.
`422`	`error`	Validation failed. `data` lists the field errors.
`429`	`error`	Rate limit exceeded — see Rate limiting.
`500`	`error`	An unexpected server error.

Successful responses are always 200

Write endpoints (create, update) also return 200 — not 201 — on success. Branch on meta.status, and read the created or updated resource from data.

Validation errors (422)

When a request fails validation, the response is HTTP 422. meta.message carries a summary, and data is a flat array of field errors, one entry per failing rule:

{
  "meta": {
    "code": 422,
    "status": "error",
    "message": "The name field is required."
  },
  "data": [
    {
      "code": 0,
      "message": "The name field is required.",
      "field": "name"
    },
    {
      "code": 0,
      "message": "The selected branch is invalid.",
      "field": "branch"
    }
  ]
}

Each error item has:

Field	Type	Description
`code`	integer	Reserved for a future error taxonomy; currently always `0`.
`message`	string	Human-readable description of the failing rule.
`field`	string	The input field that failed.

Field names are normalised

The field value drops the _id / _ids suffix of the underlying column: a failure on branch_id is reported as field: "branch". Match on the base name, not the raw column.

Other error examples

A missing or invalid credential returns 401:

{
  "meta": {
    "code": 401,
    "status": "error",
    "message": "Unauthenticated."
  },
  "data": null
}

A resource that does not exist returns 404:

{
  "meta": {
    "code": 404,
    "status": "error",
    "message": "Resource not found."
  },
  "data": null
}

An unexpected server error returns 500 with a generic message (internal details are never leaked):

{
  "meta": {
    "code": 500,
    "status": "error",
    "message": "Something went wrong, please try again later."
  },
  "data": null
}

Don't parse messages

meta.message wording is meant for humans and may change. Branch your code on meta.code / the HTTP status and, for 422, on the field values in data — never on the message string.

The envelope

HTTP status codes

Validation errors (422)

Other error examples

On this page