Error Reference
MedRAG returns JSON errors with an error field:
{
"error": "error_code",
"message": "Optional human-readable description"
}
Error Codes
| Code | HTTP Status | Description | Resolution |
|---|---|---|---|
missing_auth | 401 | No Authorization header | Send Authorization: Bearer <api-key> |
invalid_api_key | 401 | Malformed or unknown API key | Check the key and header format |
forbidden | 403 | API key role is too low for this endpoint | Use a key with a higher role |
not_found | 404 | Resource doesn’t exist or isn’t accessible to your key | Check the resource ID |
payment_required | 402 | Account suspended for non-payment | Settle the outstanding invoice |
quota_exhausted | 402 | Free plan query quota used up | Upgrade your plan or wait for reset |
document_limit_reached | 402 | Plan’s document limit reached | Delete documents or upgrade |
chunk_quota_exceeded | 402 | Plan’s chunk limit reached | Delete documents or upgrade |
knowledge_base_limit_reached | 403 | Plan’s knowledge base limit reached | Upgrade your plan |
enterprise_plan_required | 403 | Endpoint needs the Enterprise plan | Upgrade your plan |
addon_not_enabled | 403 | Transcription/report add-on not enabled | Enable the add-on |
document_too_large | 413 | Document exceeds the plan’s size limit (max_bytes returned) | Reduce document size or upgrade |
sub_tenant_storage_quota_exceeded | 413 | Sub-tenant storage quota reached (current, limit returned) | Raise the sub-tenant quota or delete documents |
validation_error / message | 422 | Invalid request body | Check required fields and formats |
rate_limit_exceeded | 429 | Too many requests | Wait for Retry-After seconds |
per_user_rate_limit_exceeded | 429 | Per-user limit hit (X-User-Id) | Wait for Retry-After seconds |
sub_tenant_chunk_quota_exceeded | 429 | Sub-tenant chunk quota reached | Raise the sub-tenant limit |
tenant_pool_quota_exceeded | 429 | Tenant-wide chunk pool exhausted | Upgrade or delete documents |
internal_error | 500 | Server error | Retry; contact support if persistent |
translation_unavailable / *_unavailable | 503 | Feature not available on this instance right now | Retry later |
Validation errors (422) and some others return a plain-language message in error
(for example "name must be 1-200 characters") rather than a code. Not every error includes a
message field.
Rate Limit Errors
When rate-limited, the response includes:
{
"error": "rate_limit_exceeded",
"retry_after_seconds": 5,
"docs_url": "https://docs.medrag.eu/usage-limits"
}
Quota Errors
When a plan quota is exhausted:
{"error": "quota_exhausted"}
Document and chunk limits additionally return current, limit and docs_url.