Errors

Status codes, the error body, and where per-source failures are reported

Request problems use HTTP status codes and an error body. Data source and data function problems appear inside status in an HTTP 200 response.

Error body

FastAPI errors use one detail key.

{ "detail": "Access token required" }

Validation failures use an array.

{
  "detail": [
    {
      "type": "literal_error",
      "loc": ["body", "config", "context"],
      "msg": "Input should be 'prod', 'test' or 'dev'",
      "input": "production"
    }
  ]
}

Field	Type	Description
`detail`	string or array	Message or validation errors
`detail[].type`	string	Failed validation rule
`detail[].loc`	array	Field path beginning with `body`
`detail[].msg`	string	Human-readable explanation
`detail[].input`	any	Rejected value

detail[].input echoes submitted data. Inspect it before forwarding the error. There is no stable error code or request ID. Branch on HTTP status and, for 422, detail[].loc; do not parse msg.

Status codes

Status	When	Retry guidance
`200`	Request ran; individual work may fail	Read `status`
`401`	Token or workflow rejected	Fix credentials
`404`	Path does not exist	Fix URL
`405`	Method is wrong	Use documented method
`422`	Request schema failed	Fix fields in `detail`
`500`	Valid request could not process	Retry once with backoff

There is no service-level 429 or rate-limit header.

Confirmation needed: Confirm whether clients can receive 429, 502, 503, or 504 responses and publish retry guidance if so.

401 Unauthorized

Access token required means no credential was found. Authentication failed means the token, workflow, or pairing was rejected.

422 Unprocessable Entity

Cause	`detail[].loc`
Missing `config`	`["body", "config"]`
Invalid context	`["body", "config", "context"]`
Non-object sources	`["body", "config", "sources"]`
Non-object inputs	`["body", "inputs"]`
Invalid JSON	`["body"]`

500 Internal Server Error

{ "detail": "Internal Server Error" }

An empty or missing /data config.sources currently returns 500. Always send at least one source.

Confirmation needed: Empty sources should likely return 422. Confirm whether the service will change before clients depend on the current 500.

Failures inside HTTP 200

/data status has success, message, match, and response_time_ms. /func has all except match.

Message prefix	Endpoint	Cause
`Adapter not found for`	`/data`	Unknown source
`Adapter error:`	`/data`	Credential, vendor, timeout, or input error
`Data function not found:`	`/func`	Unknown function
`Data function error:`	`/func`	Function raised an error
`Unexpected error:`	Both	Result collection failed

A data function can call several configured data sources. If one of those sources returns an error, Data Serve normally still returns HTTP 200 because the service accepted and ran the function request. Clients must inspect the response body for the function’s source-specific errors rather than relying on the HTTP status alone.

Treat non-200 as a request problem and record detail.
On 200, read status before outputs.
Treat success: true, match: false as valid no-data.
Retry only timeouts and vendor 5xx failures, only for failed sources.
Record transaction_id from every successful response.