axios

Postconditions — what we check

• get · success-2xx

  info
  Whenresponse status is 2xx
  ReturnsAxiosResponse object with data, status, statusText, headers, config, and request fields
  Required handlingNo action required — use the returned value as needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• get · error-4xx-5xx

  error
  Whenresponse status is 4xx or 5xx and validateStatus is default
  ThrowsAxiosError with error.response containing the error response
  Required handlingCaller MUST catch AxiosError and check error.response.status to distinguish between client errors (4xx) and server errors (5xx).
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• get · rate-limited-429

  error
  Whenresponse status is 429 (Too Many Requests)
  ThrowsAxiosError with error.response.status === 429
  Required handlingCaller MUST either: 1. Implement exponential backoff retry logic with the Retry-After header, OR 2. Explicitly handle 429 as a terminal error and surface to the user, OR 3. Use a request queue that respects rate limits. Silently catching and ignoring 429 without retry logic is a violation.
  costmediumin proddegraded serviceusers seedegraded performancevisibilityvisible
  Sources[2]
• get · network-failure

  error
  Whennetwork error, connection timeout, or DNS resolution failure
  ThrowsAxiosError with error.request populated but error.response === undefined
  Required handlingCaller MUST check if error.response exists before accessing error.response.status. Network errors have error.request but NO error.response property. Code that assumes error.response is always present will crash.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• get · request-setup-error

  warning
  Whenerror during request setup (before request is sent)
  ThrowsAxiosError with both error.request === undefined and error.response === undefined
  Required handlingCaller MUST handle errors where neither error.request nor error.response exist. These are configuration or setup errors.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• post · success-2xx

  info
  Whenresponse status is 2xx
  ReturnsAxiosResponse object
  Required handlingNo action required — use the returned value as needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• post · error-4xx-5xx

  error
  Whenresponse status is 4xx or 5xx
  ThrowsAxiosError with error.response
  Required handlingCaller MUST catch AxiosError and inspect error.response.status
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• post · rate-limited-429

  error
  Whenresponse status is 429
  ThrowsAxiosError with error.response.status === 429
  Required handlingFor POST requests, retry logic MUST be idempotency-aware. Either use idempotency keys or handle 429 as terminal error.
  costmediumin proddegraded serviceusers seedegraded performancevisibilityvisible
  Sources[2]
• post · network-failure

  error
  Whennetwork error, timeout, or DNS failure
  ThrowsAxiosError with error.response === undefined
  Required handlingCheck error.response exists before accessing error.response.status
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• put · error-4xx-5xx

  error
  Whenresponse status is 4xx or 5xx
  ThrowsAxiosError
  Required handlingCaller MUST catch AxiosError and inspect error.response.status
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• put · network-failure

  error
  Whennetwork error or timeout
  ThrowsAxiosError with error.response === undefined
  Required handlingCheck error.response exists before accessing error.response.status
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• delete · error-4xx-5xx

  error
  Whenresponse status is 4xx or 5xx
  ThrowsAxiosError
  Required handlingCaller MUST catch AxiosError and inspect error.response.status
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• delete · network-failure

  error
  Whennetwork error or timeout
  ThrowsAxiosError with error.response === undefined
  Required handlingCheck error.response exists before accessing error.response.status
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• request · error-4xx-5xx

  error
  Whenresponse status is 4xx or 5xx
  ThrowsAxiosError with error.response
  Required handlingCaller MUST catch AxiosError and check error.response.status to distinguish between client errors (4xx) and server errors (5xx)
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• request · rate-limited-429

  error
  Whenresponse status is 429 (Too Many Requests)
  ThrowsAxiosError with error.response.status === 429
  Required handlingCaller MUST either: 1. Implement exponential backoff retry logic with the Retry-After header, OR 2. Explicitly handle 429 as a terminal error and surface to the user, OR 3. Use a request queue that respects rate limits. For non-idempotent methods (POST), ensure retry safety with idempotency keys.
  costmediumin proddegraded serviceusers seedegraded performancevisibilityvisible
  Sources[2]
• request · network-failure

  error
  Whennetwork error or timeout
  ThrowsAxiosError with error.response === undefined
  Required handlingCaller MUST check if error.response exists before accessing properties. Network errors have error.request but NO error.response property.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• request · request-setup-error

  warning
  Whenerror during request setup (before request is sent)
  ThrowsAxiosError with both error.request === undefined and error.response === undefined
  Required handlingCaller MUST handle errors where neither error.request nor error.response exist. These are configuration or setup errors (e.g., invalid URL, unsupported protocol).
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• patch · patch-error-4xx-5xx

  error
  Whenresponse status is 4xx or 5xx and validateStatus is default
  ThrowsAxiosError with error.response containing status, headers, and body
  Required handlingCaller MUST catch AxiosError and check error.response.status to distinguish client errors (4xx) from server errors (5xx). Do not retry 4xx without user intervention (except 408, 413, 429).
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2][3]
• patch · patch-rate-limited-429

  error
  Whenresponse status is 429 (Too Many Requests)
  ThrowsAxiosError with error.response.status === 429
  Required handlingCaller MUST implement exponential backoff with the Retry-After header. For PATCH (partial updates), retrying is often safe if the operation is idempotent, but verify with the API's idempotency guarantees. Silently catching and ignoring 429 without retry is a violation.
  costmediumin proddegraded serviceusers seedegraded performancevisibilityvisible
  Sources[2]
• patch · patch-network-failure

  error
  Whennetwork error, timeout (ETIMEDOUT/ECONNABORTED), or DNS failure (ERR_NETWORK)
  ThrowsAxiosError with error.request populated but error.response === undefined; error.code is ETIMEDOUT, ECONNABORTED, or ERR_NETWORK
  Required handlingCaller MUST check if error.response exists before accessing error.response.status. Network errors populate error.request (the raw http.ClientRequest) but NOT error.response. Code that assumes error.response is always present will crash with TypeError.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2][4]
• head · head-error-4xx-5xx

  error
  Whenserver responds with 4xx or 5xx and validateStatus is default
  ThrowsAxiosError with error.response (status, headers) but error.response.data === ''
  Required handlingCaller MUST catch AxiosError and check error.response.status. NOTE: error.response.data is always an empty string for HEAD responses (the server sends no body). Do not attempt to parse error body for HEAD requests.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2][5]
• head · head-network-failure

  error
  Whennetwork error, connection timeout, or DNS failure
  ThrowsAxiosError with error.request populated but error.response === undefined
  Required handlingCaller MUST check error.response exists before accessing it. Network errors do not populate error.response — accessing error.response.status will throw TypeError: Cannot read properties of undefined.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• postForm · postform-error-4xx-5xx

  error
  Whenserver responds with 4xx or 5xx and validateStatus is default
  ThrowsAxiosError with error.response containing status and body
  Required handlingCaller MUST catch AxiosError and inspect error.response.status. File upload failures (413 Payload Too Large, 415 Unsupported Media Type, 422 Unprocessable Entity) are common and must be handled explicitly.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[2][6]
• postForm · postform-payload-too-large-413

  error
  Whenserver responds with 413 Payload Too Large
  ThrowsAxiosError with error.response.status === 413
  Required handlingCaller MUST handle 413 explicitly for file upload flows. Options: 1. Check file size before upload and reject files exceeding the limit. 2. Split large files into chunks and upload in parts. 3. Surface a specific error to the user ("File too large, max 10MB"). Silently catching 413 causes silent upload failure with no user feedback.
  costhighin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[7][2]
• postForm · postform-network-failure

  error
  Whennetwork error, connection timeout, or DNS failure during upload
  ThrowsAxiosError with error.request populated but error.response === undefined
  Required handlingCaller MUST check error.response exists before accessing it. File uploads are more susceptible to network timeouts (large payloads). Consider setting an explicit timeout and implementing retry with resume capability.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[2]
• postForm · postform-serialization-error

  warning
  WhenFormData serialization fails due to incompatible or circular data
  ThrowsAxiosError with error.code === 'ERR_BAD_REQUEST' or native TypeError from serializer
  Required handlingCaller SHOULD validate data before passing to postForm. Circular references in nested objects will throw during serialization (before any network request). Custom visitor functions (config.formSerializer) that throw will surface as unhandled exceptions if not wrapped in try-catch.
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[6][4]
• putForm · putform-error-4xx-5xx

  error
  Whenserver responds with 4xx or 5xx
  ThrowsAxiosError with error.response
  Required handlingCaller MUST catch AxiosError. For file replacement flows, handle 413 (file too large) and 415 (unsupported media type) explicitly. PUT is idempotent, so retrying is safe for network failures but will replace the resource again.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[2][6]
• putForm · putform-network-failure

  error
  Whennetwork error or timeout
  ThrowsAxiosError with error.response === undefined
  Required handlingCaller MUST check error.response exists. PUT is idempotent — retrying after network failure is safe and recommended, but verify the server has not already processed the request (check with HEAD or GET before retrying).
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[2]
• query · query-error-4xx-5xx

  error
  Whenresponse status is 4xx or 5xx and validateStatus is default
  ThrowsAxiosError with error.response containing status, headers, and body
  Required handlingCaller MUST catch AxiosError and check error.response.status to distinguish client errors (4xx — bad query payload, unsupported QUERY method on the target endpoint, 405 Method Not Allowed) from server errors (5xx). Many servers/proxies do not yet implement QUERY and will return 405 or 501 — handle these explicitly.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[8][2]
• query · query-method-not-allowed-405

  error
  Whenserver responds with 405 Method Not Allowed or 501 Not Implemented
  ThrowsAxiosError with error.response.status === 405 or 501
  Required handlingCaller MUST handle 405/501 explicitly for QUERY requests. QUERY is a newer HTTP method (still on the standards track) and many origins, CDNs, reverse proxies, and WAFs reject it. Fall back to POST + idempotency key, or surface a clear error indicating the upstream does not support QUERY. Silently catching this and retrying as POST may change resource semantics if the server treats POST as non-idempotent.
  costmediumin proddegraded serviceusers seeservice unavailablevisibilityvisible
  Sources[9][10]
• query · query-rate-limited-429

  error
  Whenresponse status is 429 (Too Many Requests)
  ThrowsAxiosError with error.response.status === 429
  Required handlingCaller MUST implement exponential backoff with the Retry-After header. QUERY is safe AND idempotent per the HTTPbis draft, so retrying after 429 is safe (unlike POST/PATCH where retry safety depends on idempotency keys). Silently catching and ignoring 429 without retry logic is a violation.
  costmediumin proddegraded serviceusers seedegraded performancevisibilityvisible
  Sources[2][8]
• query · query-network-failure

  error
  Whennetwork error, connection timeout (ETIMEDOUT/ECONNABORTED), connection refused (ECONNREFUSED), or DNS failure (ERR_NETWORK)
  ThrowsAxiosError with error.request populated but error.response === undefined; error.code is ETIMEDOUT, ECONNABORTED, ECONNREFUSED, or ERR_NETWORK
  Required handlingCaller MUST check error.response exists before accessing error.response.status. Network errors populate error.request (raw http.ClientRequest) but NOT error.response. The ECONNREFUSED constant was added in axios 1.16.0 (PR #10680) so callers can match connection-refused failures via AxiosError.ECONNREFUSED instead of string-compare on the code field. Because QUERY is safe and idempotent, retry on network failure is safe — but bound the retry budget to avoid hammering an unreachable origin.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2][4][11]
• patchForm · patchform-error-4xx-5xx

  error
  Whenserver responds with 4xx or 5xx
  ThrowsAxiosError with error.response
  Required handlingCaller MUST catch AxiosError. Handle 413 (file too large) and 415 (unsupported media type) explicitly. PATCH is not guaranteed idempotent — do not blindly retry without understanding the server's idempotency semantics.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[2][6]
• patchForm · patchform-network-failure

  error
  Whennetwork error or timeout
  ThrowsAxiosError with error.response === undefined
  Required handlingCaller MUST check error.response exists before accessing. Do not blindly retry patchForm on network failure — PATCH may not be idempotent. Use idempotency keys or check state before retrying.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[2]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]axios-http.com/docs/res_schemahttps://axios-http.com/docs/res_schema
2. [2]axios-http.com/docs/handling_errorshttps://axios-http.com/docs/handling_errors
3. [3]axios-http.com/docs/api_introhttps://axios-http.com/docs/api_intro
4. [4]github.com/axios/axioshttps://github.com/axios/axios/blob/v1.x/lib/core/AxiosError.js
5. [5]developer.mozilla.org/en-US/docshttps://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD
6. [6]axios-http.com/docs/multiparthttps://axios-http.com/docs/multipart
7. [7]developer.mozilla.org/en-US/docshttps://developer.mozilla.org/en-US/docs/Web/HTTP/Status/413
8. [8]github.com/axios/axioshttps://github.com/axios/axios/pull/10802
9. [9]ietf.org/archive/idhttps://www.ietf.org/archive/id/draft-ietf-httpbis-safe-method-w-body-09.html
10. [10]developer.mozilla.org/en-US/docshttps://developer.mozilla.org/en-US/docs/Web/HTTP/Status/405
11. [11]github.com/axios/axioshttps://github.com/axios/axios/pull/10680
12. [12]axios-http.com/docs/req_confighttps://axios-http.com/docs/req_config