https://ipbase.com/docs/_next/static/chunks/pages/status-codes-2c854f59c7fbbc03.js

1(self.webpackChunk_N_E=self.webpackChunk_N_E||[]).push([[319],{2302:(s,e,o)=>{"use strict";o.r(e),o.d(e,{__N_SSG:()=>r,default:()=>i});var n=o(7876),a=o(1668);function t(s){let e=Object.assign({h1:"h1",p:"p",code:"code",hr:"hr",h2:"h2",a:"a",pre:"pre"},(0,a.RP)(),s.components),{Note:o,Properties:t,Property:r}=e;return o||p("Note",!0),t||p("Properties",!0),r||p("Property",!0),(0,n.jsxs)(n.Fragment,{children:[(0,n.jsx)(e.h1,{children:"Request Status Codes"}),"\n",(0,n.jsxs)(e.p,{children:["You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the error type and error message to figure out what has gone wrong and do some rudimentary debugging (before contacting support). A successful request will be returned with status code ",(0,n.jsx)(e.code,{children:"200"}),"."],...{className:"lead"}}),"\n",(0,n.jsx)(o,{children:(0,n.jsx)(e.p,{children:"Before reaching out to support with an error, please be aware that 99% of all\nreported errors are, in fact, user errors. Therefore, please carefully check\nyour code before contacting ipbase support."})}),"\n",(0,n.jsx)(e.hr,{}),"\n",(0,n.jsx)(e.h2,{id:"status-codes",children:"Status codes"}),"\n",(0,n.jsx)(e.p,{children:"Here is a list of the different categories of status codes returned by the ipbase API. Use these to understand if a request was successful."}),"\n",(0,n.jsxs)(t,{children:[(0,n.jsx)(r,{name:"200",children:(0,n.jsxs)(e.p,{children:[(0,n.jsx)("span",{id:"_200"}),"A 200 status code indicates a successful response."]})}),(0,n.jsx)(r,{name:"401",children:(0,n.jsxs)(e.p,{children:[(0,n.jsx)("span",{id:"_401"}),"A 401 status code indicates that the API key you supplied is invalid. Double-check the key against your ",(0,n.jsx)(e.a,{href:"https://app.ipbase.com/dashboard",children:"dashboard"}),"."]})}),(0,n.jsx)(r,{name:"403",children:(0,n.jsxs)(e.p,{children:[(0,n.jsx)("span",{id:"_403"}),"A 403 status code indicates that you are not allowed to use this endpoint, ",(0,n.jsx)(e.a,{href:"https://app.ipbase.com/subscription",children:"please upgrade your plan"}),"."]})}),(0,n.jsx)(r,{name:"404",children:(0,n.jsxs)(e.p,{children:[(0,n.jsx)("span",{id:"_404"}),"A 404 status code indicates that a requested endpoint does not exist, or that no data was found for the requested IP or ASN."]})}),(0,n.jsx)(r,{name:"422",children:(0,n.jsxs)(e.p,{children:[(0,n.jsx)("span",{id:"_422"}),"A 422 status code indicates that one or more request parameters failed validation — for example an invalid ",(0,n.jsx)(e.code,{children:"ip"})," or an unsupported ",(0,n.jsx)(e.code,{children:"language"}),". The response body contains a ",(0,n.jsx)(e.code,{children:"message"})," and an ",(0,n.jsx)(e.code,{children:"errors"})," object describing each rejected parameter (see below)."]})}),(0,n.jsx)(r,{name:"429",children:(0,n.jsxs)(e.p,{children:[(0,n.jsx)("span",{id:"_429"}),"A 429 status code indicates that you have hit your rate limit or your monthly limit. For more requests ",(0,n.jsx)(e.a,{href:"https://app.ipbase.com/subscription",children:"please upgrade your plan"}),"."]})}),(0,n.jsx)(r,{name:"500",children:(0,n.jsxs)(e.p,{children:[(0,n.jsx)("span",{id:"_500"}),"A 500 status code indicates a internal server error - let us know: ",(0,n.jsx)(e.a,{href:"mailto:[email protected]",children:"[email protected]"})]})})]}),"\n",(0,n.jsx)(e.hr,{}),"\n",(0,n.jsx)(e.h2,{id:"error-responses",children:"Error responses"}),"\n",(0,n.jsxs)(e.p,{children:["Every error response is JSON and always contains a human-readable ",(0,n.jsx)(e.code,{children:"message"}),". Responses with status ",(0,n.jsx)(e.code,{children:"401"}),", ",(0,n.jsx)(e.code,{children:"403"}),", ",(0,n.jsx)(e.code,{children:"404"})," and ",(0,n.jsx)(e.code,{children:"429"})," additionally carry a machine-readable envelope: an ",(0,n.jsx)(e.code,{children:"error"})," object with a stable ",(0,n.jsx)(e.code,{children:"code"}),", an ",(0,n.jsx)(e.code,{children:"actions"})," object with URLs for the most useful next steps and — for quota errors — a ",(0,n.jsx)(e.code,{children:"quota"})," object with your current usage. Where available, an ",(0,n.jsx)(e.code,{children:"info"})," field links back to this page."]}),"\n",(0,n.jsx)(e.pre,{language:"json",code:'{\n    "message": "Validation error",\n    "errors": {\n        "ip": [\n            "The ip field must be a valid IP address."\n        ]\n    },\n    "info": "For more information, see documentation: https://ipbase.com/docs/status-codes#_422"\n}\n',children:(0,n.jsx)(e.code,{className:"language-json",children:'<span><span style="color: var(--shiki-color-text)">{</span></span>\n<span><span style="color: var(--shiki-color-text)">    </span><span style="color: var(--shiki-token-keyword)">&quot;message&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">&quot;Validation error&quot;</span><span style="color: var(--shiki-token-punctuation)">,</span></span>\n<span><span style="color: var(--shiki-color-text)">    </span><span style="color: var(--shiki-token-keyword)">&quot;errors&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> {</span></span>\n<span><span style="color: var(--shiki-color-text)">        </span><span style="color: var(--shiki-token-keyword)">&quot;ip&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> [</span></span>\n<span><span style="color: var(--shiki-color-text)">            </span><span style="color: var(--shiki-token-string-expression)">&quot;The ip field must be a valid IP address.&quot;</span></span>\n<span><span style="color: var(--shiki-color-text)">        ]</span></span>\n<span><span style="color: var(--shiki-color-text)">    }</span><span style="color: var(--shiki-token-punctuation)">,</span></span>\n<span><span style="color: var(--shiki-color-text)">    </span><span style="color: var(--shiki-token-keyword)">&quot;info&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">&quot;For more information, see documentation: https://ipbase.com/docs/status-codes#_422&quot;</span></span>\n<span><span style="color: var(--shiki-color-text)">}</span></span>\n<span></span>'}),...{title:"Example 422 response"}}),"\n",(0,n.jsx)(e.pre,{language:"json",code:'{\n    "message": "You used all your monthly requests. Please upgrade your plan at https://app.ipbase.com/subscription",\n    "error": {\n        "code": "quota_exceeded",\n        "message": "You used all your monthly requests. Please upgrade your plan at https://app.ipbase.com/subscription"\n    },\n    "quota": {\n        "limit": 300,\n        "used": 300,\n        "remaining": 0,\n        "resets_at": "2026-09-01T00:00:00+00:00"\n    },\n    "actions": {\n        "upgrade": "https://app.ipbase.com/subscription?utm_source=api_error&utm_campaign=quota_exceeded",\n        "docs": "https://ipbase.com/docs/openapi.yaml"\n    }\n}\n',children:(0,n.jsx)(e.code,{className:"language-json",children:'<span><span style="color: var(--shiki-color-text)">{</span></span>\n<span><span style="color: var(--shiki-color-text)">    </span><span style="color: var(--shiki-token-keyword)">&quot;message&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">&quot;You used all your monthly requests. Please upgrade your plan at https://app.ipbase.com/subscription&quot;</span><span style="color: var(--shiki-token-punctuation)">,</span></span>\n<span><span style="color: var(--shiki-color-text)">    </span><span style="color: var(--shiki-token-keyword)">&quot;error&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> {</span></span>\n<span><span style="color: var(--shiki-color-text)">        </span><span style="color: var(--shiki-token-keyword)">&quot;code&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">&quot;quota_exceeded&quot;</span><span style="color: var(--shiki-token-punctuation)">,</span></span>\n<span><span style="color: var(--shiki-color-text)">        </span><span style="color: var(--shiki-token-keyword)">&quot;message&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">&quot;You used all your monthly requests. Please upgrade your plan at https://app.ipbase.com/subscription&quot;</span></span>\n<span><span style="color: var(--shiki-color-text)">    }</span><span style="color: var(--shiki-token-punctuation)">,</span></span>\n<span><span style="color: var(--shiki-color-text)">    </span><span style="color: var(--shiki-token-keyword)">&quot;quota&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> {</span></span>\n<span><span style="color: var(--shiki-color-text)">        </span><span style="color: var(--shiki-token-keyword)">&quot;limit&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-constant)">300</span><span style="color: var(--shiki-token-punctuation)">,</span></span>\n<span><span style="color: var(--shiki-color-text)">        </span><span style="color: var(--shiki-token-keyword)">&quot;used&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-constant)">300</span><span style="color: var(--shiki-token-punctuation)">,</span></span>\n<span><span style="color: var(--shiki-color-text)">        </span><span style="color: var(--shiki-token-keyword)">&quot;remaining&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-constant)">0</span><span style="color: var(--shiki-token-punctuation)">,</span></span>\n<span><span style="color: var(--shiki-color-text)">        </span><span style="color: var(--shiki-token-keyword)">&quot;resets_at&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">&quot;2026-09-01T00:00:00+00:00&quot;</span></span>\n<span><span style="color: var(--shiki-color-text)">    }</span><span style="color: var(--shiki-token-punctuation)">,</span></span>\n<span><span style="color: var(--shiki-color-text)">    </span><span style="color: var(--shiki-token-keyword)">&quot;actions&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> {</span></span>\n<span><span style="color: var(--shiki-color-text)">        </span><span style="color: var(--shiki-token-keyword)">&quot;upgrade&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">&quot;https://app.ipbase.com/subscription?utm_source=api_error&amp;utm_campaign=quota_exceeded&quot;</span><span style="color: var(--shiki-token-punctuation)">,</span></span>\n<span><span style="color: var(--shiki-color-text)">        </span><span style="color: var(--shiki-token-keyword)">&quot;docs&quot;</span><span style="color: var(--shiki-token-punctuation)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">&quot;https://ipbase.com/docs/openapi.yaml&quot;</span></span>\n<span><span style="color: var(--shiki-color-text)">    }</span></span>\n<span><span style="color: var(--shiki-color-text)">}</span></span>\n<span></span>'}),...{title:"Example 429 response with error envelope"}}

1),"\n",(0,n.jsxs)(e.p,{children:["Error codes you may encounter include ",(0,n.jsx)(e.code,{children:"missing_api_key"}),", ",(0,n.jsx)(e.code,{children:"invalid_api_key"}),", ",(0,n.jsx)(e.code,{children:"quota_exceeded"}),", ",(0,n.jsx)(e.code,{children:"grace_quota_exceeded"}),", ",(0,n.jsx)(e.code,{children:"overage_quota_exceeded"}),", ",(0,n.jsx)(e.code,{children:"rate_limit_exceeded"}),", ",(0,n.jsx)(e.code,{children:"not_found"})," and ",(0,n.jsx)(e.code,{children:"forbidden"}),"."]}),"\n",(0,n.jsx)(e.hr,{}),"\n",(0,n.jsx)(e.h2,{id:"validation-errors",children:"Validation errors"}),"\n",(0,n.jsxs)(e.p,{children:["If your request fails with a ",(0,n.jsx)(e.code,{children:"422"})," status code, the ",(0,n.jsx)(e.code,{children:"errors"})," object in the response body tells you exactly which parameter was rejected and why. These are the most common validation errors:"]}),"\n",(0,n.jsxs)(t,{children:[(0,n.jsx)(r,{name:"Invalid IP",children:(0,n.jsxs)(e.p,{children:["The ",(0,n.jsx)(e.code,{children:"ip"})," field must be a valid IP address."]})}),(0,n.jsx)(r,{name:"Missing IP",children:(0,n.jsxs)(e.p,{children:["The ",(0,n.jsx)(e.code,{children:"ip"})," parameter is required."]})}),(0,n.jsx)(r,{name:"Invalid language",children:(0,n.jsxs)(e.p,{children:["The selected ",(0,n.jsx)(e.code,{children:"language"})," is invalid and should be an ISO Alpha 2 Language Code for localising the ip data."]})})]}),"\n",(0,n.jsx)(e.hr,{})]})}var r=!0;let i=function(s={}){let{wrapper:e}=Object.assign({},(0,a.RP)(),s.components);return e?(0,n.jsx)(e,Object.assign({},s,{children:(0,n.jsx)(t,s)})):t(s)};function p(s,e){throw Error("Expected "+(e?"component":"object")+" `"+s+"` to be defined: you likely forgot to import, pass, or provide it.")}},3362:(s,e,o)=>{(window.__NEXT_P=window.__NEXT_P||[]).push(["/status-codes",function(){return o(2302)}])}},s=>{s.O(0,[636,593,792],()=>s(s.s=3362)),_N_E=s.O()}]);