Errors
Madeenan returns simple JSON errors. Read the HTTP status first, then the detail code.
What This Does
Error responses help you separate authentication issues, validation issues, hosted chat issues, and rate limits.
Minimal Response
{
"detail": "hosted_chat_not_configured"
}
Status Codes
| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
| 400 | HTTP | No | — | Invalid payload, hosted chat configuration issue, unsupported option, or provider error. |
| 401 | HTTP | No | — | Missing or invalid Madeenan API key or admin token. |
| 403 | HTTP | No | — | Missing scope or blocked origin. |
| 404 | HTTP | No | — | The requested source, session, or app was not found. |
| 429 | HTTP | No | — | Rate limit exceeded. See Rate Limits for retry guidance. |
| 500 | HTTP | No | — | Unexpected server error. |
Hosted Chat Errors
{
"detail": "provider_rate_limited"
}
| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
| provider_bad_request | detail | No | — | The hosted model provider rejected the request body or model parameters. |
| hosted_chat_not_configured | detail | No | — | Hosted chat is not configured on the Madeenan server. |
| provider_rate_limited | detail | No | — | The hosted model account hit its own quota or rate limit. |
| provider_timeout | detail | No | — | The hosted model provider did not respond in time. |
Common Mistakes
- Retrying 401 or 403 responses instead of fixing credentials.
- Treating hosted chat errors as Madeenan retrieval errors.
- Retrying 429s without backoff. Use the Rate Limits guide.
Model/provider note
Hosted chat is quota limited for testing and lightweight use. Production apps should call
/v1/search, then use their own model provider from their backend.