Loading...
FinchTrade

Definition

API response

An API response is the reply to an API request. In HTTP APIs, status codes, headers, and an optional body convey outcomes, metadata, and data.

An API response is the reply returned after a request is made to an application programming interface (API). It can carry requested information, describe an operation’s outcome, or report an error. The request asks the API to do something; the response communicates the result. HTTP status codes and headers are features of HTTP-based APIs, not of every API.

How an API Response Works

In a typical request–reply exchange, a client sends a request to an endpoint, the address that exposes a particular API function or resource. The server receives the request, processes it, and sends a reply. The client then interprets the API response according to the API’s documented rules, including any outcome information and returned content.

For example, a request might ask for a resource’s current details or ask the server to create a resource. The corresponding reply may contain those details, indicate the operation’s result, or explain why it could not proceed. Receiving a reply does not, by itself, mean the requested action succeeded.

Parts of an HTTP Response

For an HTTP-based API response, the status code communicates the HTTP-level outcome. Headers supply metadata that helps the client interpret the reply; for example, a Content-Type header identifies the body’s media type. The optional body carries returned data or error details.

A body field named status belongs to the API’s own data structure and is not the HTTP status code. Its meaning depends on the documentation and may describe a resource or business operation rather than the HTTP exchange. The phrase “status line” refers to the textual representation used in HTTP/1.1, where a numeric code can appear alongside a reason phrase. That layout is not universal across HTTP versions, so it should not be treated as the structure of every response.

FinchTrade services

Success and Error Outcomes

HTTP status codes are grouped by outcome. Codes in the 2xx range indicate HTTP-level success: 200 OK commonly accompanies a successful retrieval, 201 Created indicates that one or more resources were created, and 204 No Content indicates success without a response body. These are illustrative examples, not a required response template. A successful POST request does not always return 201.

Codes in the 4xx range indicate perceived client or request errors, while 5xx codes indicate server errors. A 400 Bad Request covers a broader range of perceived client errors than malformed body syntax alone. A 401 Unauthorized response means valid authentication credentials are missing. A 403 Forbidden response means the server understood the request but refuses to fulfill it; the reason need not concern credentials. A 404 Not Found response means no current representation was found, or the server will not disclose one. A 500 Internal Server Error response indicates an unexpected server condition preventing fulfillment. An API response reporting an error may include explanatory content, but an error body is not guaranteed. A connection or transport failure may leave the client with no HTTP response at all, which is different from receiving an error status.

Response Formats and Empty Bodies

JSON and XML are examples of response-body formats, not requirements. An API response can also contain plain text, HTML, binary content, or another documented representation. The API documentation specifies the expected fields, their types, and what their values mean; JSON syntax alone does not define that structure.

A response can legitimately have no body, whether because no returned content is needed or because HTTP rules prohibit it, as with 204 responses and responses to HEAD requests. The absence of content must be understood alongside the status code, headers, and documentation. An empty body is not automatically an error, and a populated body is not automatically evidence of success.

Interpreting a Reply in Practice

As a hypothetical exchange, a client could send a POST request to /api/resource with the JSON body {"name":"New Resource"}. A response body such as {"status":"success","data":{"id":123}} would contain an application-defined status and a resource identifier. The client first checks the actual HTTP outcome and content type, then parses the JSON and validates the fields against the documented schema. The example describes an invented API, not a universal contract.

Error handling can record useful diagnostic details without exposing credentials or personal data, display a clear message, and keep unaffected functions available. A failed or interrupted request should not trigger an unconditional retry: a write may already have taken effect even if its reply was lost. Recovery therefore depends on the operation’s documented semantics and duplicate-prevention provisions, rather than the status code alone.

Power your growth with seamless crypto liquidity

A single gateway to liquidity with competitive prices, fast settlements, and lightning-fast issue resolution

Get started