Use an existing Gateway Key

This path is for an application developer who has a Gateway Key and a public model alias. You do not need Admin Console access or the identity of the upstream provider.

Before you start

Before you start

Item	Example	Source
Instance URL	https://halro.example.com	Your administrator; Halro has no universal hosted URL
Gateway Key	gw_ followed by 43 characters	Shown once when the administrator creates it
Route alias	chat	A public name defined by the administrator

Base URL difference

The OpenAI SDK base URL includes /v1. The Anthropic SDK base URL does not. A wrong base URL normally returns 404.

Keep the key out of shell history

read -r -s HALRO_GATEWAY_KEY
printf '\n'
export HALRO_GATEWAY_KEY

Send the first request

curl https://halro.example.com/v1/chat/completions \
  -H "Authorization: Bearer $HALRO_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chat",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Introduce Halro in one sentence."}]
  }'

Set an explicit output limit. It bounds provider output and the conservative budget reservation used when the network result is uncertain. This example uses max_tokens instead of max_completion_tokens: the latter is declared unsupported on the DeepSeek path, and the public alias does not reveal which path will be selected.

Interpret the first failure

Interpret the first failure

HTTP	Code	Meaning and next action
401	invalid_api_key	Missing, malformed, revoked, or wrong key. Ask for a new Gateway Key; do not substitute a Provider key.
404	model_not_found	No Route has this alias. Confirm the public alias with the administrator.
403	model_not_allowed	The Route exists but your Project is not authorized for it.
400	unsupported_feature	No eligible target supports the requested operation or field. Remove the feature or ask about eligible Deployment/Profile combinations.
503	provider_unavailable	No healthy eligible Deployment. Apply bounded backoff.
403	token_guard_blocked	A fixed threshold or temporary block rejected the request before Provider I/O. Do not retry blindly.
429	several codes	The retry decision depends on the exact code and whether Retry-After is present.

Halro does not expose GET /v1/models on the Gateway. Public aliases belong to the Project and do not reveal their upstream targets. See authentication, request headers, and errors for client handling.

“Does my alias support tool calls?”

The alias alone cannot answer. A Route can contain multiple Deployments bound to different Provider Profiles. A field is available only when eligible targets remain after capability filtering, not because an alias implies one fixed Profile.

You have three practical options:

1. Probe directly. Send a minimal request with tools. An unsupported request is rejected before Provider I/O, so it incurs no Provider cost and cannot return a partial answer.
2. Ask a precise administrator question. Ask which Deployment/Profile targets remain eligible for chat when tools are requested and whether fallback is permitted; compare each target with the Chat Completions reference.
3. Implement degradation. Branch on the stable unsupported-feature error and retry the business action without tools only when that behavior is acceptable.

See Scenario 1 for complete Project, Key, and Route separation across environments.

Remove the key when the shell no longer needs it:

unset HALRO_GATEWAY_KEY