[{"data":1,"prerenderedAt":814},["ShallowReactive",2],{"/api/overview/errors":3,"/api/overview/errors-surround":805},{"id":4,"title":5,"body":6,"description":796,"extension":797,"links":798,"meta":799,"navigation":800,"path":801,"seo":802,"stem":803,"__hash__":804},"docs/api/1.overview/errors.md","Errors",{"type":7,"value":8,"toc":785},"minimark",[9,26,49,54,131,213,228,232,241,374,390,397,421,424,486,492,498,595,605,609,725,728,746,750,781],[10,11,12,13,17,18,21,22,25],"p",{},"The Capacities HTTP API signals outcome with standard HTTP status codes. Successful responses use ",[14,15,16],"code",{},"2xx",". Responses in the ",[14,19,20],{},"4xx"," range mean the request was not accepted (authentication, validation, permissions, rate limits, etc.). Responses in the ",[14,23,24],{},"5xx"," range mean something failed on the server side.",[10,27,28,29,33,34,36,37,40,41,44,45,48],{},"Error responses use a ",[30,31,32],"strong",{},"consistent JSON body",": a stable machine-readable ",[14,35,14],{}," (always prefixed with ",[14,38,39],{},"cap_","), a human-readable ",[14,42,43],{},"message",", and optionally structured ",[14,46,47],{},"details"," for specific failure types.",[50,51,53],"h2",{"id":52},"error-response-format","Error response format",[55,56,61],"pre",{"className":57,"code":58,"language":59,"meta":60,"style":60},"language-json shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","{\n  \"code\": \"cap_invalid_input\",\n  \"message\": \"✖ Invalid input: expected string, received number\\n  → at title\"\n}\n","json","",[14,62,63,72,99,125],{"__ignoreMap":60},[64,65,68],"span",{"class":66,"line":67},"line",1,[64,69,71],{"class":70},"sMK4o","{\n",[64,73,75,78,81,84,87,90,94,96],{"class":66,"line":74},2,[64,76,77],{"class":70},"  \"",[64,79,14],{"class":80},"spNyl",[64,82,83],{"class":70},"\"",[64,85,86],{"class":70},":",[64,88,89],{"class":70}," \"",[64,91,93],{"class":92},"sfazB","cap_invalid_input",[64,95,83],{"class":70},[64,97,98],{"class":70},",\n",[64,100,102,104,106,108,110,112,115,119,122],{"class":66,"line":101},3,[64,103,77],{"class":70},[64,105,43],{"class":80},[64,107,83],{"class":70},[64,109,86],{"class":70},[64,111,89],{"class":70},[64,113,114],{"class":92},"✖ Invalid input: expected string, received number",[64,116,118],{"class":117},"sTEyZ","\\n",[64,120,121],{"class":92},"  → at title",[64,123,124],{"class":70},"\"\n",[64,126,128],{"class":66,"line":127},4,[64,129,130],{"class":70},"}\n",[132,133,134,150],"table",{},[135,136,137],"thead",{},[138,139,140,144,147],"tr",{},[141,142,143],"th",{},"Field",[141,145,146],{},"Type",[141,148,149],{},"Description",[151,152,153,173,197],"tbody",{},[138,154,155,160,163],{},[156,157,158],"td",{},[14,159,14],{},[156,161,162],{},"string",[156,164,165,166,168,169,172],{},"Stable identifier for programmatic handling. Values use the ",[14,167,39],{}," prefix (for example ",[14,170,171],{},"cap_not_authenticated",").",[138,174,175,179,181],{},[156,176,177],{},[14,178,43],{},[156,180,162],{},[156,182,183,184,186,187,190,191,193,194,196],{},"Human-readable explanation. For validation failures (",[14,185,93],{},"), this is often a ",[30,188,189],{},"multi-line summary"," with field paths. Wording can change between API versions—use ",[14,192,14],{}," to branch, not the exact ",[14,195,43],{}," text.",[138,198,199,203,206],{},[156,200,201],{},[14,202,47],{},[156,204,205],{},"optional",[156,207,208,209,212],{},"Structured context for ",[30,210,211],{},"certain codes only"," (for example missing OAuth scopes). Omitted when there is nothing extra to attach. Not used for validation errors.",[10,214,215,216,218,219,221,222,224,225,227],{},"Use ",[14,217,14],{}," (and ",[14,220,47],{}," when present) for programmatic handling. For ",[14,223,93],{},", read ",[14,226,43],{}," for debugging or displaying validation feedback to end users.",[50,229,231],{"id":230},"error-codes","Error codes",[10,233,234,235,237,238,240],{},"Every published ",[14,236,14],{}," is part of the API contract. Prefer matching on ",[14,239,14],{}," in your integration and SDK.",[132,242,243,257],{},[135,244,245],{},[138,246,247,251,254],{},[141,248,249],{},[14,250,14],{},[141,252,253],{},"Typical HTTP status",[141,255,256],{},"Meaning",[151,258,259,273,288,303,324,344,359],{},[138,260,261,265,270],{},[156,262,263],{},[14,264,171],{},[156,266,267],{},[14,268,269],{},"401",[156,271,272],{},"Missing, invalid, or expired bearer token, or the token cannot be used for this request.",[138,274,275,280,285],{},[156,276,277],{},[14,278,279],{},"cap_scope_insufficient",[156,281,282],{},[14,283,284],{},"403",[156,286,287],{},"The token does not include the scopes required for this operation.",[138,289,290,295,300],{},[156,291,292],{},[14,293,294],{},"cap_not_found",[156,296,297],{},[14,298,299],{},"404",[156,301,302],{},"The requested resource does not exist or is not visible with this token.",[138,304,305,309,318],{},[156,306,307],{},[14,308,93],{},[156,310,311,314,315],{},[14,312,313],{},"400",", ",[14,316,317],{},"413",[156,319,320,321,323],{},"Request body, query, or parameters failed validation, or the payload is too large. Validation detail is in ",[14,322,43],{},".",[138,325,326,331,336],{},[156,327,328],{},[14,329,330],{},"cap_rate_limit_exceeded",[156,332,333],{},[14,334,335],{},"429",[156,337,338,339,323],{},"Too many requests in the rate-limit window for this endpoint or token. See ",[340,341,343],"a",{"href":342},"/api/overview/rate-limiting","Rate limiting",[138,345,346,351,356],{},[156,347,348],{},[14,349,350],{},"cap_server_error",[156,352,353],{},[14,354,355],{},"500",[156,357,358],{},"An unexpected error occurred on the server. Retrying may succeed; contact support if it persists.",[138,360,361,366,371],{},[156,362,363],{},[14,364,365],{},"cap_service_unavailable",[156,367,368],{},[14,369,370],{},"503",[156,372,373],{},"The service is temporarily unavailable (maintenance or overload). Retry with backoff.",[10,375,376,377,379,380,383,384,387,388,323],{},"The HTTP status and ",[14,378,14],{}," are aligned: your client should treat ",[14,381,382],{},"(status, code)"," as the source of truth. Some edge responses may use a status that fits HTTP semantics (for example ",[14,385,386],{},"413 Payload Too Large",") while still using ",[14,389,93],{},[50,391,393,394,396],{"id":392},"validation-errors-cap_invalid_input","Validation errors (",[14,395,93],{},")",[10,398,399,400,402,403,407,408,411,412,415,416,418,419,323],{},"When request validation fails, the API responds with ",[14,401,93],{},". The ",[30,404,405],{},[14,406,43],{}," field contains a readable multi-line summary (issue lines, often with ",[14,409,410],{},"→ at \u003Cpath>"," locations). There is ",[30,413,414],{},"no"," ",[14,417,47],{}," field for validation—the formatted string is only in ",[14,420,43],{},[10,422,423],{},"Example (illustrative shape only):",[55,425,427],{"className":57,"code":426,"language":59,"meta":60,"style":60},"{\n  \"code\": \"cap_invalid_input\",\n  \"message\": \"✖ Required\\n  → at title\\n✖ String must contain at most 3000 characters\\n  → at body.content\"\n}\n",[14,428,429,433,451,482],{"__ignoreMap":60},[64,430,431],{"class":66,"line":67},[64,432,71],{"class":70},[64,434,435,437,439,441,443,445,447,449],{"class":66,"line":74},[64,436,77],{"class":70},[64,438,14],{"class":80},[64,440,83],{"class":70},[64,442,86],{"class":70},[64,444,89],{"class":70},[64,446,93],{"class":92},[64,448,83],{"class":70},[64,450,98],{"class":70},[64,452,453,455,457,459,461,463,466,468,470,472,475,477,480],{"class":66,"line":101},[64,454,77],{"class":70},[64,456,43],{"class":80},[64,458,83],{"class":70},[64,460,86],{"class":70},[64,462,89],{"class":70},[64,464,465],{"class":92},"✖ Required",[64,467,118],{"class":117},[64,469,121],{"class":92},[64,471,118],{"class":117},[64,473,474],{"class":92},"✖ String must contain at most 3000 characters",[64,476,118],{"class":117},[64,478,479],{"class":92},"  → at body.content",[64,481,124],{"class":70},[64,483,484],{"class":66,"line":127},[64,485,130],{"class":70},[50,487,489,490,396],{"id":488},"details-for-permissions-cap_scope_insufficient","Details for permissions (",[14,491,279],{},[10,493,494,495,497],{},"When the token is authenticated but lacks required scopes, ",[14,496,47],{}," may include which scopes are missing:",[55,499,501],{"className":57,"code":500,"language":59,"meta":60,"style":60},"{\n  \"code\": \"cap_scope_insufficient\",\n  \"message\": \"The request requires additional API permissions.\",\n  \"details\": {\n    \"missingScopes\": [\"api:write\"]\n  }\n}\n",[14,502,503,507,525,544,557,584,590],{"__ignoreMap":60},[64,504,505],{"class":66,"line":67},[64,506,71],{"class":70},[64,508,509,511,513,515,517,519,521,523],{"class":66,"line":74},[64,510,77],{"class":70},[64,512,14],{"class":80},[64,514,83],{"class":70},[64,516,86],{"class":70},[64,518,89],{"class":70},[64,520,279],{"class":92},[64,522,83],{"class":70},[64,524,98],{"class":70},[64,526,527,529,531,533,535,537,540,542],{"class":66,"line":101},[64,528,77],{"class":70},[64,530,43],{"class":80},[64,532,83],{"class":70},[64,534,86],{"class":70},[64,536,89],{"class":70},[64,538,539],{"class":92},"The request requires additional API permissions.",[64,541,83],{"class":70},[64,543,98],{"class":70},[64,545,546,548,550,552,554],{"class":66,"line":127},[64,547,77],{"class":70},[64,549,47],{"class":80},[64,551,83],{"class":70},[64,553,86],{"class":70},[64,555,556],{"class":70}," {\n",[64,558,560,563,567,569,571,574,576,579,581],{"class":66,"line":559},5,[64,561,562],{"class":70},"    \"",[64,564,566],{"class":565},"sBMFI","missingScopes",[64,568,83],{"class":70},[64,570,86],{"class":70},[64,572,573],{"class":70}," [",[64,575,83],{"class":70},[64,577,578],{"class":92},"api:write",[64,580,83],{"class":70},[64,582,583],{"class":70},"]\n",[64,585,587],{"class":66,"line":586},6,[64,588,589],{"class":70},"  }\n",[64,591,593],{"class":66,"line":592},7,[64,594,130],{"class":70},[10,596,215,597,599,600,602,603,323],{},[14,598,566],{}," to prompt users to re-authorize or adjust API token permissions—not every response includes ",[14,601,47],{}," if the situation is already clear from ",[14,604,43],{},[50,606,608],{"id":607},"http-status-reference","HTTP status reference",[132,610,611,621],{},[135,612,613],{},[138,614,615,618],{},[141,616,617],{},"Status",[141,619,620],{},"When it applies",[151,622,623,637,648,659,670,681,692,703,714],{},[138,624,625,634],{},[156,626,627,630,631],{},[14,628,629],{},"200","–",[14,632,633],{},"299",[156,635,636],{},"Success.",[138,638,639,643],{},[156,640,641],{},[14,642,313],{},[156,644,645,646,172],{},"Bad request / validation (often with ",[14,647,93],{},[138,649,650,654],{},[156,651,652],{},[14,653,269],{},[156,655,656,657,172],{},"Not authenticated (",[14,658,171],{},[138,660,661,665],{},[156,662,663],{},[14,664,284],{},[156,666,667,668,172],{},"Authenticated but not allowed—often scope-related (",[14,669,279],{},[138,671,672,676],{},[156,673,674],{},[14,675,299],{},[156,677,678,679,172],{},"Not found (",[14,680,294],{},[138,682,683,687],{},[156,684,685],{},[14,686,317],{},[156,688,689,690,172],{},"Request entity too large (",[14,691,93],{},[138,693,694,698],{},[156,695,696],{},[14,697,335],{},[156,699,700,701,172],{},"Rate limited (",[14,702,330],{},[138,704,705,709],{},[156,706,707],{},[14,708,355],{},[156,710,711,712,172],{},"Server error (",[14,713,350],{},[138,715,716,720],{},[156,717,718],{},[14,719,370],{},[156,721,722,723,172],{},"Service unavailable (",[14,724,365],{},[50,726,343],{"id":727},"rate-limiting",[10,729,730,732,733,735,736,738,739,742,743,745],{},[14,731,335],{}," responses use the same JSON shape; ",[14,734,14],{}," is ",[14,737,330],{},". Check standard rate-limit headers (for example ",[14,740,741],{},"RateLimit-*",") and ",[340,744,343],{"href":342}," for retry guidance.",[50,747,749],{"id":748},"typescript-sdk","TypeScript SDK",[10,751,752,753,761,762,765,766,314,769,771,772,774,775,777,778,780],{},"The ",[340,754,758],{"href":755,"rel":756},"https://www.npmjs.com/package/@capacities/api",[757],"nofollow",[14,759,760],{},"@capacities/api"," client maps failed HTTP responses to ",[14,763,764],{},"CapacitiesApiError",", with ",[14,767,768],{},"status",[14,770,14],{},", and optional ",[14,773,47],{}," (for scope errors). For validation failures, inspect ",[14,776,43],{},". Prefer handling ",[14,779,14],{}," rather than parsing free-text ad hoc.",[782,783,784],"style",{},"html pre.shiki code .sMK4o, html code.shiki .sMK4o{--shiki-light:#39ADB5;--shiki-default:#89DDFF;--shiki-dark:#89DDFF}html pre.shiki code .spNyl, html code.shiki .spNyl{--shiki-light:#9C3EDA;--shiki-default:#C792EA;--shiki-dark:#C792EA}html pre.shiki code .sfazB, html code.shiki .sfazB{--shiki-light:#91B859;--shiki-default:#C3E88D;--shiki-dark:#C3E88D}html pre.shiki code .sTEyZ, html code.shiki .sTEyZ{--shiki-light:#90A4AE;--shiki-default:#EEFFFF;--shiki-dark:#BABED8}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}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);}html pre.shiki code .sBMFI, html code.shiki .sBMFI{--shiki-light:#E2931D;--shiki-default:#FFCB6B;--shiki-dark:#FFCB6B}",{"title":60,"searchDepth":67,"depth":74,"links":786},[787,788,789,791,793,794,795],{"id":52,"depth":74,"text":53},{"id":230,"depth":74,"text":231},{"id":392,"depth":74,"text":790},"Validation errors (cap_invalid_input)",{"id":488,"depth":74,"text":792},"Details for permissions (cap_scope_insufficient)",{"id":607,"depth":74,"text":608},{"id":727,"depth":74,"text":343},{"id":748,"depth":74,"text":749},"HTTP status codes, error payloads, and machine-readable codes returned by the Capacities API.","md",null,{},true,"/api/overview/errors",{"title":5,"description":796},"api/1.overview/errors","snrknGECHxd3hZwe5y1ez18KkWT_VAnyCu23KfoLuqw",[806,810],{"title":807,"path":808,"stem":809,"children":-1},"Concurrency","/api/overview/concurrency","api/1.overview/concurrency",{"title":811,"path":812,"stem":813,"children":-1},"Migration from Beta to v1","/api/overview/migration","api/1.overview/migration",1781012285071]