Errors
Madeenan returns simple JSON errors. Read the HTTP status first, then the detail code.
What This Does
Each error response states its category: authentication, validation, hosted chat, or rate limiting.
Minimal Response
{
"detail": "hosted_chat_not_configured"
}
Status Codes
| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
| 400 | HTTP | No | — | The payload is invalid, an option is unsupported, or a hosted chat call failed. |
| 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 429 responses without backoff. Copy the backoff pattern from Rate Limits.
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.