Every error includes recovery_action (what to do next) and docs_url for AI Agent auto-handling.
{
"error": "PROVIDER_RATE_LIMITED",
"http_status": 429,
"message": "Provider rate-limited the request for "openai-chat". Try again shortly.",
"request_id": "req_abc123",
"suggestion": "try_later",
"recovery_action": "Wait 10-60s and retry, or use batch deduplication to reduce call volume.",
"docs_url": "https://apitree.ai/docs/errors#rate-limit"
}UNAUTHORIZED401Request a new API key and retry with Authorization: Bearer <key>FORBIDDEN403Check plan tier or organization role; upgrade via /pricingNOT_FOUND404Confirm API slug exists via GET /api/v1/apis?q=<term>RATE_LIMIT_EXCEEDED429Back off and retry after Retry-After header. Upgrade tier for higher limitsPROVIDER_RATE_LIMITED429Provider rate-limited. Wait 10-60s, or use batch deduplicationAUTH_FAILURE401Provider rejected credentials. Verify/rotate via adminINSUFFICIENT_CREDITS402Top up credits or upgrade plan at /pricingPROVIDER_TIMEOUT504Upstream took too long. Retry once; consider alternative providerPROVIDER_CIRCUIT_OPEN503Provider failing repeatedly. Wait ~30s for circuit resetINVALID_BATCH400Batch body must be { calls: [{api, method?, path?, params?}] } with 1-10 entriesBATCH_TOO_LARGE400Split into multiple batches of at most 10 calls eachPAYLOAD_TOO_LARGE413Reduce request body below 1MB. Stream or paginate large payloadsCALL_FAILED502Inspect message field. If transient, retry with exponential backoff (max 3)