FAQ

Minimal self-check

Check the model catalog and a minimal chat separately, then diagnose using the complete error response.

1. Are the key and network fine?

curl https://api.smartwan.com/v1/models \
  -H "Authorization: Bearer ***"

A returned list proves this catalog request passed, not that every model is authorized or can perform inference.

2. Does chat work?

curl https://api.smartwan.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "ping"}],
    "max_tokens": 1024
  }'

If the first succeeds and the second fails, also check model permissions, balance, routes, endpoint and parameters. The request body or model name is not the only possible cause.

Error codes

Error	Common cause	What to do
401	Authentication failed	Check the key, state and header. Messages accepts x-api-key or Bearer; see Authentication
400	Parameter, role, tool or protocol mismatch, among other causes	Keep error.code/type/message; reduce to the protocol's minimal request, then restore parameters individually
403	Permission or account restrictions, among other causes	Check model authorization and account state using the response; do not assume the model was retired
404	Path or resource mismatch, among other causes	OpenAI / Messages use /v1; native Gemini uses /v1beta. Check for duplicate SDK version paths
429	Rate or quota limits, among other causes	Follow the response: lower concurrency, wait before retrying or check limits
500	Gateway conversion or upstream errors, among other causes	Keep the error and request ID; verify Responses support per model
503 / 504	Unavailable routes or timeouts, among other causes	Record the model and time, check route status, and retry or use a verified fallback when appropriate

What exactly goes in Base URL

The most frequent question. Find your case:

Case	What to enter
base_url / baseURL in the OpenAI SDK	https://api.smartwan.com/v1
Anthropic Python SDK	https://api.smartwan.com; the SDK appends /v1/messages
Google GenAI Python SDK	https://api.smartwan.com; set api_version="v1beta"
curl against the OpenAI-compatible endpoint	https://api.smartwan.com/v1/chat/completions
curl against the Anthropic endpoint	https://api.smartwan.com/v1/messages
curl against the Gemini endpoint	https://api.smartwan.com/v1beta/models/{model}:generateContent
Client tools	https://api.smartwan.com, with or without /v1 — follow that tool's page

If you see a path like /v1/v1/chat/completions, you've entered /v1 twice.

Verified endpoint status

Tests on 2026-09-22 covered Chat Completions for 36 catalog text models, representative Messages / Responses / native Gemini calls, and generation and decoding for three image models. See Authentication & Base URL and Vendor differences for client versions, model names and differences.

Parameters verified to work

Verification applies to specific request combinations, not every parameter. Tests covered both Messages authentication methods, Claude tool history and thinking round-trips, two Kimi K3 temperatures, and DeepSeek Flash / Pro reasoning output.

This run did not cover streaming across every protocol, all image-generation parameters, image editing, masks or streaming edits. These capabilities cannot be marked verified from this run.

Known model parameter limits

kimi-k3 succeeded with both temperature: 1 and 0.3, so a universal restriction to 1 is incorrect. HTTP 200 also does not guarantee a complete answer: check finish_reason, reasoning usage and output budget if final text is empty. See Vendor differences.

Specific problems

The model list is empty or won't load

The key lacks permission, the account has no quota, or the tool failed to refresh. Run the self-check above to see whether /v1/models responds.

Config saves fine in the tool, but chatting errors out

Check Base URL, model name and API type, then use the error response to check permissions, quota and routes. Always copy the model name from Models rather than typing it.

The model name is reported as nonexistent

Names are case-sensitive: MiniMax-M2.7 is not minimax-m2.7. Models are also retired over time, so an example name in the docs may no longer exist — the live model list is authoritative.

A parameter error, but you don't know which parameter

Use the minimum required fields for the chosen protocol; Messages also requires max_tokens, for example. Start from First Call, then add parameters back individually.

Image generation fails

Confirm the model is gpt-image-2, and test with just the basics first: prompt, n, size.

response_format=url on the image endpoint doesn't return an external link

Parse the actual fields: GPT / Grok returned decodable data[].b64_json, while Gemini returned inlineData. Do not only look for an external URL. See First Call for formats and dimension checks.

Image editing errors

Check model editing support and upload a valid file matching the endpoint requirements. Preserve the error response. Editing, masks and streaming edits were not tested in this run, so do not attribute errors to a specific parameter without evidence.

Responses requests fail in Codex CLI

Reproduce with a verified GPT model and configuration. Other models can return different protocol or parameter errors; Chat Completions success does not establish Responses support. See Codex CLI.

Claude returns 400 inside agent tools

Check the error, tool schemas, request size and context. A request with 32 tool definitions also passed this test, so count alone does not establish the cause. See the Hermes Claude profile.

Account and quota

Lost an API Key — check Copy again in Quota & API Keys; availability depends on permissions and key state. Rotate the key if exposure is suspected.

Can't create a key — inspect the creation error and check your role, department and quota conditions; contact your administrator when needed.

Where to see usage — the console's "Usage Center", filterable by department, member, key and model, with CSV export.

Where to see pricing — the model pricing page in the console. This documentation site does not display prices.

What to include when contacting support

Record the failure time and timezone, model, endpoint path, client name and version, HTTP status, and error.code/type/message. Include a request ID if present; the gateway may return it in x-oneapi-request-id or the error message.

This authentication error format was observed in testing, with the request ID replaced. The code field can be empty, so do not inspect that field alone:

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: REDACTED)",
    "type": "new_api_error"
  }
}

Copy this template, removing API keys, Authorization / Cookie values, actual email addresses and sensitive business content:

Failure time and timezone:
Client and version:
Request method and endpoint path:
Model name:
HTTP status:
error.code / type / message:
Request ID, if available:
Redacted minimal request body:
Does the model catalog request succeed?
Does the minimal request reproduce the failure?

Do not send a complete key or unredacted curl -v output. Check authentication and permissions for 401 / 403, and correct invalid parameters for parameter-related 400 errors. Decide whether the failure is retryable before repeating the request.