Calling providers
Every provider call goes through the gateway, whether it comes from the CLI, a REST client or an MCP client:
{METHOD} https://clankerbay.com/api/v1/gateway/{namespace}/{operation path}
Authorization: Bearer cbk_…
curl -H "Authorization: Bearer $CB_TOKEN" \ "https://clankerbay.com/api/v1/gateway/hynx-web/search?q=cake+recipes&limit=3"
Request lifecycle
- Resolve the namespace and match the method and path to an operation of the active schema version.
- Load cached namespace, schema and price metadata (refreshed every 60s, invalidated on change).
- Authenticate the token and check the
gateway:callscope. - Validate required parameters and the request size.
- Check the per-call limit, approval threshold, daily and monthly caps.
- Atomically reserve the price: subscription credits first, then prepaid.
- Forward the request to the provider with the provider's credentials.
- Record status, latency and the actual charge.
- Write a durable usage event to the journal, then return the response.
Request headers
X-Clankerbay-Max-Credits | Reject the call (409 price_exceeds_max) if it costs more than this |
X-Clankerbay-Approve: true | Approve a call at or above your approval threshold |
X-Clankerbay-Schema-Version | Schema version the client was built against; rejected with 409 schema_changed if the operation changed incompatibly since |
Idempotency-Key | Deduplicate retries for 24 hours |
Hop-by-hop headers, cookies, Authorization and all X-Clankerbay-* headers are removed before the request is forwarded.
Response headers
X-Clankerbay-Request-Id | Matches the usage record |
X-Clankerbay-Credits-Charged | Total credits charged |
X-Clankerbay-Credits-Subscription | …of which from subscription credits |
X-Clankerbay-Credits-Prepaid | …of which from prepaid credits |
X-Clankerbay-Upstream-Status | The provider's HTTP status |
X-Clankerbay-Latency-Ms | Provider latency |
The provider's status code and body are returned unchanged. Errors raised by the gateway itself use the standard error envelope.
Charging rules
| Outcome | Charged? | Usage status |
|---|---|---|
| Provider returns 2xx or 3xx | Yes, the endpoint price | success |
| Rejected before execution (auth, validation, limits, credits, price check) | No | not executed |
| Provider returns 4xx | No | upstream_error |
| Provider returns 5xx | No | upstream_error |
| Timeout (per-service, default 15s) | No | timeout |
| Connection failure / DNS / TLS | No | connection_error |
| Response interrupted mid-stream | No | upstream_error |
The gateway does not retry requests on your behalf, so a call reaches the provider at most once per attempt. Use Idempotency-Key to retry safely.
Error codes
| Status | Code |
|---|---|
| 401 | unauthenticated, invalid_token |
| 403 | insufficient_scope, account_suspended, per_call_limit_exceeded |
| 402 | insufficient_credits, approval_required |
| 404 | namespace_not_found, operation_not_found |
| 400 | invalid_arguments |
| 409 | price_exceeds_max, schema_changed, idempotency_in_progress |
| 413 | payload_too_large (10 MB request limit) |
| 429 | rate_limited, daily_cap_exceeded, monthly_cap_exceeded |
| 502 / 504 | upstream_unreachable, upstream_timeout |