Why APIs Behave the Way They Do

Part 3 of the “APIs for Non-Engineers” Series

This article continues from the previous piece, "The Anatomy of an API Request," where we explored how requests and responses are structured.

In this part, we look at the behaviours that APIs show in practical, everyday situations i.e errors, delays, rate limits, version changes, and differences across environments. These behaviours can seem confusing if you’re not working directly with the underlying systems.

The goal here is to explain these patterns in simple, relatable terms. If any expressions feel unfamiliar, you may refer to the glossary here.

Understanding Error Responses in APIs

APIs follow specific rules so that systems can communicate consistently.

When a request does not meet these rules, or when the system cannot complete the requested task, the API returns an error.

These errors are standardised, allowing teams to quickly understand what went wrong.

i) 400 - Bad Request

This status code occurs when something essential is missing or formatted incorrectly.

For example, if a system expects an email address but receives a blank field, it cannot process the request.

ii) 401 - Unauthorized

This status code happens when the request lacks valid permission.

If a user’s login token expires while using a dashboard, the API will block further actions until the user logs in again.

iii) 403 - Forbidden

This status code means the requester is recognised but not allowed to access that specific information.

A support dashboard, for instance, might allow viewing customer profiles but not financial details.

iv) 404 - Not Found

The requested resource does not exist.

This may occur if someone tries to view a customer record that was deleted or never existed.

v) 409 - Conflict

This status code means the requested action conflicts with the system’s current state.

A payroll system attempting to create a duplicate monthly record would trigger this response.

vi) 500 - Internal Server Error

A general system error.

Database interruptions, failed internal processes, or unexpected conditions may cause this.

vii) 502 / 503 / 504 - Temporary Availability Issues

These indicate that the API or a dependent service is temporarily unavailable or responding slowly.

For example, if an external bank verification service slows down, the API may return a temporary error.

Rate Limits and How They Protect System Stability

Rate limits restrict the number of requests a single user or application can make within a specific time window.

They exist to protect overall system stability.

Imagine a budgeting application that refreshes bank data every few seconds for thousands of users. Without rate limits, the bank’s systems could easily become overloaded.

A limit such as “60 requests per minute” ensures fair and controlled usage.

If a system exceeds that limit, it receives a 429 Too Many Requests response.

Rate limits prevent unintentional strain and help keep the service reliable for everyone.

What Causes API Delays and Timeouts

A timeout occurs when a system takes longer than expected to respond.

Most APIs enforce time limits to prevent processes from running indefinitely.

Several factors can contribute to delays:

large data sets being processed
high user traffic
network congestion
slow responses from dependent external services
complex calculations or queries

Consider a year-end report generation in a payroll system. If the API must compile hundreds of transactions, the request may exceed the allowed time and result in a timeout.

This does not always indicate a failure; sometimes it reflects the size or complexity of the task.

API Versioning and How Systems Evolve Over Time

APIs evolve as products grow. New business requirements, clearer data structures, performance improvements, or better ways of organising information often lead teams to release a new version of the API.

Versioning allows a product to improve without disrupting customers or internal tools that still rely on earlier structures.

A version is usually included in the API’s URL, such as:

https://api.company.com/v1/customers
https://api.company.com/v2/customers

Both endpoints may exist at the same time, but they may behave differently.

For example:

v1 might return a single “status” field
v2 might return a detailed object with timestamps and delivery steps

A real-world pattern might look like this:

Old version:

GET /v1/orders/123 → returns:
```
{
  "status": "complete"
}
```

New version:

GET /v2/orders/123 → returns:

{
  "status": "delivered",
  "delivered_at": "2025-03-01T10:32:00Z",
  "timeline": [
    {"event": "Dispatched", "time": "..."},
    {"event": "In transit", "time": "..."},
    {"event": "Delivered", "time": "..."}
  ]
}

In many organisations, versioning is handled by:

prefixing the URL (/v1/, /v2/)
using a query parameter (/orders?version=1) - less common
versioning within headers - more advanced, mainly used in large-scale APIs

The URL-prefix style (/v1/, /v2/) is the simplest and most widely used, especially in fintech, SaaS, and internal APIs.

Versioning is a sign of progress as it allows systems to improve without breaking the tools that already depend on earlier versions.

Differences Between Sandbox, Staging, and Production

Most APIs operate in multiple environments, each serving a different purpose:

Sandbox – safe for experimenting; often uses simulated data
Staging – closely mirrors production for final testing
Production – real users and real data

These environments often behave differently. For example, a Sandbox environment may return immediate sample data, while the Production environment may enforce additional checks or limits that slow some responses.

Understanding these differences helps avoid confusion when behaviour varies between environments.

Reasons API Responses Can Change Over Time

API responses often reflect real-time or frequently updated information.

For that reason, identical requests can return different results at different times.

If a metrics dashboard requests “today’s transactions,” the number will naturally change as new activity occurs.

Permissions can also influence responses. A user with limited access may see fewer details than one with full privileges.

Variation in responses usually reflects changing data or context rather than system inconsistency.

The Importance of Consistency in API Behaviour

APIs are intentionally strict because consistent behavior is essential for reliable communication between systems.

Predictable behaviour such as structured errors, defined limits, and versioning, ensure that:

integrations do not break unexpectedly
performance remains stable
data remains accurate
teams know what to expect
systems can scale safely

These rules are designed to prevent ambiguity and help systems interact smoothly.

How Understanding API Behaviour Helps Non-Engineers

A solid understanding of these behaviours helps non-engineering professionals:

describe issues more accurately
set realistic expectations for customers and stakeholders
collaborate more effectively with engineering teams
understand the limits and possibilities of product features
anticipate common sources of errors
troubleshoot small issues independently

You do not need to write code to benefit from understanding API patterns.

Recognising how and why APIs behave the way they do helps you work more confidently around them.

Next in the Series

The next article explores Understanding API Authentication: Keys, Tokens, Secrets, in Plain English. This will provide a clear overview of how systems verify identity, what different authentication methods mean, and why authentication sometimes fails.

Understanding these concepts helps explain why certain actions require specific permissions and how security is managed in API interactions.

Test Your Knowledge

Take a quiz to test your knowledge of error responses, rate limits, timeouts, versioning, and API behavior by clicking this button: