API Errors

Save the HTTP status, response body, request time with time zone, and model ID. A client's translated “connection failed” message is not enough to diagnose the cause.

400 Bad Request

The JSON may be invalid, a required field may be missing, a value may have the wrong type, the model may reject an optional parameter, or request formats from different protocols may have been mixed. Retry with only the required fields from the matching protocol guide.

401 / 403 Authentication or permission

Check the complete key with no whitespace, the correct protocol header, key status and expiration, remaining account and key quota, group-model compatibility, and model/IP restrictions.

404 URL, endpoint, or model

Look for /v1/v1, a complete endpoint pasted into a Base URL field, an altered model ID, or a client sending one protocol's body to another protocol's path.

429 Too Many Requests

429 can represent request rate, concurrency, or upstream congestion. Use exponential backoff with random jitter, honor Retry-After when present, limit concurrent retries, and set a maximum retry count and total time budget. Do not retry deterministic validation or permission errors.

500 / 502 / 503 Service error

Verify the minimal request first. A side-effect-free text request may be retried after a short backoff. Do not retry every 5xx indefinitely; image jobs and tool workflows may already have run or incurred charges.

Timeout without an HTTP status

Check DNS, TLS, local proxies, firewalls, client timeouts, and streaming buffers. Use curl directly before debugging a complex client.

Record a redacted report in this format:

Time and time zone:
Client and version:
Protocol:
Request URL (without key):
Model:
HTTP status:
Response error code and message:
Matching Sprelay usage log: yes / no

This template deliberately excludes the API key and private request body.