Skip to content

API Request & Response

An API request asks an API to retrieve information or perform an action, while the response communicates the resulting data, status, or error.

An API request is a message sent to an API asking it to retrieve information or perform an action.

The response is the message returned after the API processes that request.

Together, requests and responses form the basic interaction pattern of many APIs.

What a Request Can Contain

An API request may contain:

For example:

POST /contacts

{
  "name": "Jane Smith",
  "email": "jane@example.com"
}

asks the API to create a contact with the supplied information.

What a Response Can Contain

A response may include:

A successful response might return:

{
  "id": 1842,
  "name": "Jane Smith"
}

A failed response may instead explain why the request could not be completed.

Status Codes

HTTP response status codes indicate the broad result of the request.

MDN's HTTP status-code reference groups responses into informational, successful, redirection, client-error, and server-error classes.

Your existing **HTTP Status Code** glossary term provides the broader website context.

Why It Matters

An integration should not simply:

send request → assume success.

It needs to evaluate the response.

For example:

  • 200 may indicate success
  • 201 may indicate creation
  • 400 may indicate invalid input
  • 401 may indicate missing authentication
  • 404 may indicate a missing resource
  • 429 may indicate a Rate Limit
  • 500 may indicate a server problem

The correct handling depends on the API.

Common Problems

Common problems include:

  • Ignoring response codes
  • Assuming every successful response has the same shape
  • Retrying permanent errors
  • Logging failures without alerting anyone
  • Treating network failure as confirmation that an action did not happen
  • Parsing only one possible response format

How to Improve

Handle success and failure deliberately.

Document which responses:

  • Complete the workflow
  • Need correction
  • Can be retried
  • Require authentication
  • Need human intervention

For actions that may be repeated after uncertain failures, Idempotency becomes especially important.