Skip to main content

Errors

When a request fails, Shisa services signal the problem with an HTTP status code and a JSON body describing what went wrong. This guide covers the status codes you will see, the JSON shapes that carry the detail, and where to find per-endpoint error tables.

HTTP status codes​

Check the response status first — it tells you the category of the problem and how to resolve it.

StatusMeaningHow to resolve
400Bad request — invalid or missing parametersCheck the request body and required fields; see the error message for the specific field.
401Authentication failedVerify your API key and the per-service header form. See Authentication.
429Rate limit exceededSlow down and retry with backoff. See Rate limits.
500Server error or service not readyRetry after a short delay; if it persists, contact support via the platform.

JSON error shapes​

Error bodies come in two shapes across the services. Always read the HTTP status first, then parse the body for the human-readable error field.

Simple errors​

Some endpoints return a compact body with a numeric code and an error message. For example, an ASR request with no audio attached:

{
  "code": 400,
  "error": "No audio data provided"
}

Authentication errors​

Authentication failures (seen on ASR and TTS) return a richer body that also identifies the middleware and a named error type:

{
  "context": ["authMiddleware"],
  "code": 104,
  "name": "ErrAuthenticationFailed",
  "error": "Authentication error: Invalid token"
}

An Invalid token error almost always means the Authorization header is wrong for that service — for example a missing shsk: prefix on ASR or Translation. Review the per-service header conventions.

tip

Always check response.ok (or the status code) before parsing the body. A 429 or 500 may not contain the JSON your success path expects, so branching on status first avoids a second, confusing parse error.

Checking status before parsing, in practice:

const response = await fetch(url, options);
if (!response.ok) {
  const detail = await response.json().catch(() => ({}));
  throw new Error(`Shisa request failed (${response.status}): ${detail.error ?? 'unknown error'}`);
}
const data = await response.json();
response = requests.post(url, headers=headers, json=payload)
if not response.ok:
    detail = response.json() if response.content else {}
    raise RuntimeError(f"Shisa request failed ({response.status_code}): {detail.get('error', 'unknown error')}")
data = response.json()

Per-service error details​

Error fields and exact messages vary by endpoint. For endpoint-specific error tables and request requirements, see each service's API reference:

Next steps​