Public interface / Failure contract

Errors stay predictable and machine-readable.

Failures never become empty success responses and never disclose secrets, stack traces or private candidate data.

400

Invalid query

A query parameter is unknown, empty or outside its limit.

404

Not found

The requested versioned resource does not exist.

405

Method not allowed

The public data endpoints accept GET and HEAD only.

429

Rate limit exceeded

The configured Cloudflare limiter rejected the request.

500

Internal error

The request failed without exposing internal details.

503

Unavailable

A required durable service or production binding is absent.

Problem shape

{
  "type": "https://neobankdb.com/problems/invalid-query",
  "title": "Invalid query",
  "status": 400,
  "detail": "Human-readable boundary",
  "instance": "/v1/providers"
}