Errors#

Every non-2xx response returns the same JSON envelope.

Envelope#

{
  "code": "HTTP_401",
  "status": 401,
  "title": "Unauthorized",
  "detail": "API token not provided"
}

Field	Description
`code`	Machine-readable error code — see Error codes below
`status`	HTTP status code (also set on the response itself)
`title`	Short, human-readable summary of the error class
`detail`	Specific detail for this occurrence of the error
`errors`	Present only on `422` validation failures — see below

Validation errors#

422 responses include a field-level errors array in addition to the standard envelope:

{
  "code": "VALIDATION_ERROR",
  "status": 422,
  "title": "Validation Error",
  "detail": null,
  "errors": [
    { "field": "config.url", "message": "The config.url field is required" }
  ]
}

A single request can fail multiple fields at once — errors contains one entry per failed rule, not just the first.

Error codes#

Code	Status	Meaning
`HTTP_400`	400	Bad Request — malformed JSON body, or a required header is missing/invalid
`HTTP_401`	401	Unauthorized — token missing, invalid, or the wrong type for this endpoint
`HTTP_404`	404	Not Found — the requested resource doesn’t exist
`HTTP_405`	405	Method Not Allowed — the path exists but not for this HTTP method
`HTTP_415`	415	Unsupported Media Type — `Content-Type` must be `application/json` on write requests
`VALIDATION_ERROR`	422	Request body failed field validation — see `errors`
`JUNCTION_0000`	500	Unexpected server error

JUNCTION_0000 covers anything unanticipated — it deliberately doesn’t leak internal exception detail to the caller. If you hit one consistently, it’s worth a bug report.

Status codes#

Status	Used for
200	Successful `GET`/`PATCH`/`PUT`
201	Successful `POST /v0/destinations`
202	Successful `POST /relay` — accepted, delivery is asynchronous
204	Successful `DELETE`, and both `/system/*` endpoints
400	Bad Request
401	Unauthorized
404	Not Found
405	Method Not Allowed
415	Unsupported Media Type
422	Unprocessable Content — validation failure
500	Unexpected server error