Mansa Platform Docs
Console

Errors

Before a response starts, public endpoint failures return an RFC 7807-inspired JSON body with a non-success HTTP status. Content-Type is application/problem+json.

{
  "type": "https://platform.mymansa.ai/docs/errors#insufficient_credit",
  "title": "Insufficient Credit",
  "isError": true,
  "detail": "You do not have enough Mansa Credits for this request.",
  "invalidParams": [],
  "context": "insufficient_credit",
  "description": null
}

Use context for application logic. Human-readable detail wording can change.

Handle by context

ContextTypical HTTP statusNext action
invalid_request400Check field names, types, and limits; read invalidParams
unauthorized401Include the Bearer API key
invalid_api_key401Check the key or replace a revoked key
insufficient_credit402Add funds or reduce request size
rate_limited429Reduce concurrency and retry with backoff
service_unavailable502, 503, or 504Wait and retry a temporary failure
response_incomplete502Keep partial content; consider a shorter request
translation_failed502Retry the Translate or Transcribe request with backoff

On HTTP 400 validation failures, invalidParams lists affected fields:

{
  "context": "invalid_request",
  "invalidParams": [
    { "name": "message", "reason": "message is required." }
  ]
}

Streaming failures

Chat can return HTTP 200 and later emit an error as a final unnamed data: JSON line with isError: true, followed by data: [DONE]. Read until [DONE]. If the connection closes early, mark the partial reply incomplete. A completed reply may have meta.finishReason set to "length" when the output budget was reached.

TTS returns JSON errors only before audio starts. After that, a stream failure ends the connection. Do not decode audio bytes as JSON.

Retrying

Retry temporary failures with exponential backoff and jitter, with a bounded attempt count. Do not retry invalid input or authentication errors without correcting them. Public requests do not currently accept an idempotency key, so repeating an uncertain request can produce another charge.

For multi-turn chat, append user and assistant turns to your stored history only after a successful JSON response or a completed stream. Failed 400, 429, 502, and 503 responses must not become the next request's history. See Chat — Errors that affect history.