Errors

All SAGEA Studio APIs use standard HTTP statuses plus a stable code string for programmatic handling.

Log the request_id from every failed call and match the code below before retrying.

Status	Code	Meaning	Fix
`400`	`invalid_request`	Request body failed validation for the endpoint.	Validate required fields and types, then retry.
`400`	`missing_artifact`	Required file or object is missing from the request.	Attach the `document` or `audio_samples` file and retry.
`400`	`text_too_long`	Text `input` exceeds the 4096 character limit.	Split text at sentence boundaries and retry in chunks.
`400`	`unsupported_format`	File type or `response_format` is not supported.	Use `mp3`, PDF, PNG, JPG, TIFF, or WEBP as documented.
`401`	`unauthorized`	API key is missing, invalid, or revoked.	Re-export a valid `SAGEA_API_KEY` value and retry.
`403`	`forbidden`	Key lacks permission for this model or workspace.	Ask an admin to grant access, then retry.
`404`	`session_not_found`	Chat session or batch ID does not exist.	Poll the exact `batch_url` or recreate the session.
`404`	`verification_not_found`	Verification or KYC session ID is unknown.	Create a new verification session and retry.
`413`	`payload_too_large`	Upload exceeds the 100MB document limit.	Compress the file under 100MB and retry.
`422`	`spoof_detected`	Liveness check detected a likely spoof attempt.	Recapture with live camera and retry once.
`422`	`voice_not_found`	Voice name or `voice_id` does not exist.	Use `nova`, `atlas`, or a valid `vox_` voice ID.
`429`	`rate_limit_exceeded`	Per-minute or per-day quota was exceeded.	Back off exponentially and retry after delay.
`500`	`internal_error`	Unexpected server error processing the request.	Retry once with idempotency key, then escalate.

Error response shape

All errors return JSON with a stable code plus human readable message.

{
  "error": {
    "code": "text_too_long",
    "message": "Input exceeds 4096 characters.",
    "type": "invalid_request",
    "request_id": "req_np24500a1"
  }
}

{
  "error": {
    "code": "voice_not_found",
    "message": "Voice nova-unknown was not found.",
    "type": "not_found",
    "request_id": "req_vox_nova02"
  }
}

Always log request_id, code, and HTTP status for faster triage.

Retry guidance by product

Use these rules before contacting support to avoid duplicate charges.

Chat with sage-2-4-actus, sage-2-5-celer, and sage-oss: retry 429 and 500 with exponential backoff, do not retry 400 Kathmandu tool calls without fixing messages first.
Chat streaming: reconnect once on dropped server-sent events, then fall back to non-streaming stream set to false for the same Kathmandu prompt.
Chat JSON mode: fix response_format to type json_object on invalid_request, validate output parses before retrying the same model.
Audio with nova and atlas voices: split ne-NP greeting Welcome to SAGEA. नमस्ते on text_too_long, verify voice_id on voice_not_found, cache successful MP3 bytes.
Audio formats: switch to mp3 on unsupported_format, keep speed between 0.5 and 2.0, reuse hi-IN and es-ES hints across retries.
Voice cloning: retry missing_artifact only after adding 10 second samples, respect the 5 per day limit, reuse vox_ IDs for Hindi hi-IN prompts.
OCR with arva-ocr: compress PDFs over 100MB on payload_too_large, check NPR 24,500 invoice scans for blur on low confidence, pass language_hint of ne-NP or en-US.
OCR tables: enable bbox set to true to isolate failing blocks, retry complex NPR 24,500 tables with output_format set to json.
Helios KYC: create a fresh session on verification_not_found, recapture on spoof_detected for Aarav Sharma documents, never retry the same liveness video more than twice.
Helios documents: re-upload sharper images of Aarav Sharma citizenship cards on missing_artifact, check en-US locale mapping before resubmitting.
Mylo voice agents: reconnect streaming on internal_error once, fall back to non-streaming speech on repeated failures, log es-ES and hi-IN session IDs for review.
Mylo transcripts: poll transcript endpoints after session_not_found, back off on 429 before re-polling realtime agent sessions.

How to debug

Confirm base URL is https://api.sagea.space/v1 on every call.
Run echo $SAGEA_API_KEY to confirm the key is exported in your shell.
Print full status plus code plus request_id in application logs.
Redact file bytes and keys before sharing logs with support.
Test with a minimal curl call before retrying large batches.
Isolate one failing request from a batch before resubmitting all items.
Compare Starter versus Pro rate limits when 429 appears suddenly.
Verify voice names nova and atlas are spelled exactly before retrying.

Support

If errors persist, include the request_id, timestamp, endpoint path, and redacted headers when asking for help through the guides above.

Errors

Error response shape

Retry guidance by product

How to debug

Support

On this page