[{"data":1,"prerenderedAt":296},["ShallowReactive",2],{"doc-reference\u002Ferrors":3},{"id":4,"title":5,"author":6,"body":7,"date":279,"description":280,"draft":281,"extension":282,"faq":283,"meta":284,"navigation":285,"path":286,"schemaType":287,"seo":288,"stem":289,"tags":290,"updatedAt":294,"__hash__":295},"content\u002Freference\u002Ferrors.md","Errors","YT2Text Team",{"type":8,"value":9,"toc":275},"minimark",[10,14,18,110,115,210,214,217,250,253,271],[11,12,5],"h1",{"id":13},"errors",[15,16,17],"p",{},"Many route-level business failures use a stable envelope:",[19,20,25],"pre",{"className":21,"code":22,"language":23,"meta":24,"style":24},"language-json shiki shiki-themes github-light github-dark","{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"FEATURE_NOT_AVAILABLE\",\n    \"message\": \"Feature unavailable on current plan\",\n    \"details\": {}\n  }\n}\n","json","",[26,27,28,37,53,62,76,89,98,104],"code",{"__ignoreMap":24},[29,30,33],"span",{"class":31,"line":32},"line",1,[29,34,36],{"class":35},"sVt8B","{\n",[29,38,40,44,47,50],{"class":31,"line":39},2,[29,41,43],{"class":42},"sj4cs","  \"success\"",[29,45,46],{"class":35},": ",[29,48,49],{"class":42},"false",[29,51,52],{"class":35},",\n",[29,54,56,59],{"class":31,"line":55},3,[29,57,58],{"class":42},"  \"error\"",[29,60,61],{"class":35},": {\n",[29,63,65,68,70,74],{"class":31,"line":64},4,[29,66,67],{"class":42},"    \"code\"",[29,69,46],{"class":35},[29,71,73],{"class":72},"sZZnC","\"FEATURE_NOT_AVAILABLE\"",[29,75,52],{"class":35},[29,77,79,82,84,87],{"class":31,"line":78},5,[29,80,81],{"class":42},"    \"message\"",[29,83,46],{"class":35},[29,85,86],{"class":72},"\"Feature unavailable on current plan\"",[29,88,52],{"class":35},[29,90,92,95],{"class":31,"line":91},6,[29,93,94],{"class":42},"    \"details\"",[29,96,97],{"class":35},": {}\n",[29,99,101],{"class":31,"line":100},7,[29,102,103],{"class":35},"  }\n",[29,105,107],{"class":31,"line":106},8,[29,108,109],{"class":35},"}\n",[111,112,114],"h2",{"id":113},"common-error-codes","Common error codes",[116,117,118,125,131,144,150,156,162,168,174,180,186,192,198,204],"ul",{},[119,120,121,124],"li",{},[26,122,123],{},"INVALID_REQUEST"," – malformed payload or validation error",[119,126,127,130],{},[26,128,129],{},"UNAUTHORIZED"," – missing\u002Finvalid credentials",[119,132,133,136,137,136,140,143],{},[26,134,135],{},"INVALID_KEY"," \u002F ",[26,138,139],{},"INVALID_API_KEY",[26,141,142],{},"KEY_NOT_FOUND"," – key does not exist, malformed, or revoked",[119,145,146,149],{},[26,147,148],{},"FORBIDDEN"," – authenticated user lacks permission for this route",[119,151,152,155],{},[26,153,154],{},"RATE_LIMIT_EXCEEDED"," – too many requests in current window",[119,157,158,161],{},[26,159,160],{},"QUOTA_EXCEEDED"," – daily\u002Fplan quota is exhausted",[119,163,164,167],{},[26,165,166],{},"FEATURE_NOT_AVAILABLE"," – feature blocked for plan",[119,169,170,173],{},[26,171,172],{},"JOB_NOT_FOUND"," – unknown job id",[119,175,176,179],{},[26,177,178],{},"JOB_NOT_COMPLETED"," – result not ready yet",[119,181,182,185],{},[26,183,184],{},"JOB_FAILED"," – job failed after processing",[119,187,188,191],{},[26,189,190],{},"BATCH_NOT_FOUND"," – unknown batch id",[119,193,194,197],{},[26,195,196],{},"LIMITS_ERROR"," – internal usage\u002Flimit accounting failure",[119,199,200,203],{},[26,201,202],{},"LIST_ERROR"," – list\u002Ffilter retrieval failure",[119,205,206,209],{},[26,207,208],{},"RESULTS_ERROR"," – unable to assemble result payload",[111,211,213],{"id":212},"http-status-mapping","HTTP status mapping",[15,215,216],{},"Do not assume every failure maps cleanly to an HTTP status. The current backend mixes two patterns:",[116,218,219,226,229,232,235,238,244,247],{},[119,220,221,222,225],{},"application\u002Fbusiness-rule failures often return ",[26,223,224],{},"success: false"," via the JSON envelope",[119,227,228],{},"auth, CSRF\u002Forigin, and throttling failures are commonly raised as real HTTP errors",[119,230,231],{},"400\u002F422: request\u002Fvalidation errors",[119,233,234],{},"401: missing or invalid auth credentials",[119,236,237],{},"403: permission denied, invalid origin, CSRF failure, or runtime-disabled feature",[119,239,240,241],{},"404: missing job\u002Fbatch\u002Fresource on routes that raise ",[26,242,243],{},"HTTPException",[119,245,246],{},"429: throttled API-key request",[119,248,249],{},"500: unexpected internal failure",[15,251,252],{},"Examples of envelope-style failures that may still arrive with HTTP 200 today:",[116,254,255,259,263,267],{},[119,256,257],{},[26,258,166],{},[119,260,261],{},[26,262,160],{},[119,264,265],{},[26,266,172],{},[119,268,269],{},[26,270,178],{},[272,273,274],"style",{},"html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":24,"searchDepth":39,"depth":39,"links":276},[277,278],{"id":113,"depth":39,"text":114},{"id":212,"depth":39,"text":213},"2025-02-01","Canonical API error codes and response format",false,"md",null,{},true,"\u002Freference\u002Ferrors","TechArticle",{"title":5,"description":280},"reference\u002Ferrors",[291,292,293],"reference","operations","reliability","2026-03-22","wMBBGlQWBgTrLhbOZsZql6tU7L6tULJ_Afr0kwAOP6s",1792448457480]