Error Handling and API Response Codes

An API is a published contract between applications that specifies the exact rules for requesting and receiving services.

Programming

One Request, Several Rules

When one application uses a service owned by another application, the two sides need more than a network connection. They need shared expectations. The requesting application must know what information to send, the service must know how to interpret that request, and the requesting application must know how to interpret the response. An Application Program Interface, or API, provides those expectations as a published contract.

How do two applications use published API rules to send a request and receive a correctly structured response?

Definition

An API is a published contract between applications that specifies the exact rules for requesting and receiving services.

Tracing a Service Request

A service interaction can be understood as a sequence of state changes. First, the application identifies the functionality it needs. It then sends a request that follows the service's published rules. That request contains what is being requested, parameters that customize the request, and authentication credentials if required. The service validates the request against its API contract, processes it, and sends back a response. The response typically contains requested data in a standardized format such as JSON or XML, together with a status code indicating whether the request succeeded or failed. Finally, the application parses the response and uses the data to continue its work.

Worked example

A Travel Booking Request

A travel booking application needs to combine flight data, hotel availability, payment processing, and user account functionality.

1
Choose services
The application acts as an orchestrator and identifies the specialized services needed for the larger travel-booking goal.
2
Follow contracts
The application sends each request according to the relevant service's published API contract, including the required request information and any parameters.
3
Receive responses
Each service returns a response in a standardized format, together with a status code that indicates success or failure.
4
Combine results
The application parses the responses and combines the returned data into a cohesive user experience.

Result

Separate services contribute specialized functionality while the travel application coordinates their requests and responses.

How does data move between separate services across a network before the application can produce a result?

Monoliths and Service-Oriented Systems

A monolithic application is described in the source material as a single self-contained application. A Service-Oriented Architecture, or SOA, takes a different approach: an application is composed of multiple independent services connected across a network. Each service provides specialized functionality through its own API contract.

What is the difference between one tightly integrated application and multiple independent services working together?

Design	Structure	How functionality is accessed	Important consequence
Monolithic application	Single self-contained application	Functionality is contained within that application	The application is not described as a collection of independent network-connected services
Service-Oriented Architecture	Multiple independent services connected across a network	Applications request functionality through each service's API contract	The design supports modularity, independent scaling, team autonomy, and service reusability

The source contrasts a single self-contained monolith with multiple independent services that communicate through published contracts.

Reading Success and Failure

A response is not only a container for returned data. It also includes a status code indicating whether the request succeeded or failed. The application should therefore inspect the response before using its data. A successful response can provide data for the next stage of the application. A failed response signals that the normal path did not complete, so the application must handle that result rather than treating it as the expected data.

What happens next when an API request produces a success indication or a failure indication?

Edge case

A response can contain a standardized data format such as JSON or XML and still indicate failure through its status code. The application must consider both parts of the response: the returned format and the success-or-failure indication.

Contracts as Integration Rules

An API contract makes integration possible because both sides can work from the same published rules. The requesting application does not need to understand the service's internal implementation. It needs to know how to form a valid request and how to interpret the response. The service can then maintain its own implementation while exposing the agreed interface.

What rules must applications share so that one service can correctly understand and use another service?

Key point

The contract separates what a service offers from how the service implements it. This lets an application request functionality without needing to understand the service's internal implementation.

Mistakes in Error Handling

Common mistake
Treating an API as merely a network connection
What it looks like
An application connects to a service but does not follow the service's published request rules.
Why it fails
The service validates requests against its API contract. A connection alone does not define what information the request must contain or how the response should be interpreted.
Do this instead
Use the published API contract as the source of truth for request information, parameters, authentication requirements, response format, and status-code meaning.
Common mistake
Ignoring the response status code
What it looks like
An application parses returned data without checking whether the response indicates success or failure.
Why it fails
The response includes a status code specifically to indicate whether the request succeeded or failed.
Do this instead
Inspect the status indication before treating returned data as the successful result of the request.
Common mistake
Assuming every service exposes the same internal implementation
What it looks like
An application is designed around how a hotel service performs its search internally.
Why it fails
An API contract allows applications to request functionality without understanding the service's internal implementation.
Do this instead
Depend on the published contract rather than on undocumented internal details.
Common mistake
Assuming SOA removes all complexity
What it looks like
An application is split into services, but the design ignores communication across the network.
Why it fails
SOA introduces network dependencies and distributed system complexity even while providing modularity and service reusability.
Do this instead
Treat service communication and response handling as part of the architecture.

Practice the Trace

MEDIUM

A travel application requests hotel availability from a specialized hotel service. Explain the sequence from request to application result. Include the API contract, request validation, response data, status code, and the application's next action.

Hints

Begin with the rules published by the hotel service.
Identify what the service does before returning a response.
Explain why the application must inspect the status code before using the returned data.

Your attempt (not saved)

Worked example

Tracing the Hotel Service

Complete the request trace for the travel application when it needs hotel availability.

1
Published contract
The hotel service publishes the rules for requesting hotel availability and for receiving the response.
2
Request
The travel application sends a request that follows those rules and includes the information and parameters required by the service.
3
Validation and processing
The hotel service validates the request against its API contract and processes it.
4
Response
The hotel service sends back data in a standardized format together with a status code indicating success or failure.
5
Application action
The travel application parses the response and either uses the returned data in its larger booking work or handles the failure indication instead of treating it as a normal successful result.

Result

The contract gives both applications a shared procedure for requesting, responding, and deciding what to do next.

Key Takeaways

1
An API is a published contract that defines the rules for requesting and receiving services.
2
SOA composes an application from independent services connected across a network, unlike a single self-contained monolith.
3
Each service can maintain its own API contract and internal implementation while other applications request its functionality.
4
A service response includes returned data and a status code indicating success or failure.
5
Effective integration depends on following the published contract and handling the response indication before continuing application work.

At a glance

An API is a published contract between applications, not merely a connection between them.
Service-Oriented Architecture uses independent network-connected services to compose a larger application.
A request follows the service contract, is validated and processed, and produces a response with data and a status code.
Applications must distinguish a success indication from a failure indication before using the response as normal data.
Published contracts enable integration while allowing services to preserve independent implementations.

Related concepts

More concepts starting with E