Troubleshooting API Calls from the Response

What it is

Troubleshooting an API call means using the response, the request you sent and the documentation to find what went wrong.

The method is to compare what you sent with what the documentation requires, one part at a time. The status code tells you where to start.

Most failures are small: a wrong path, a missing header, a bad body or the wrong credentials.

How it works

Start from the status code, then check each part of the request in a fixed order.

A step by step method

1. Read the status code and the error message in the body.
2. Check the method against the documentation.
3. Check the URL, including the path, path parameters and query string.
4. Check the headers, especially Authorization, Content-Type and Accept.
5. Check the body for valid JSON, correct field names and correct value types.
6. Check the credentials, their scope and whether they have expired.

What each code usually points to

Worked example 1

The request:

POST /v1/rooms HTTP/1.1
Host: api.example.test
Authorization: Bearer ACCESS_TOKEN

{"title": "Network Ops"}

The response is 415 Unsupported Media Type. The documentation says the body must be JSON with Content-Type: application/json.

The request has no Content-Type header, so the server cannot read the body. Adding the header fixes it.

Worked example 2

The request is GET /v1/devices/9999. The response is 404 with the body {"message": "Device not found"}. The path is valid, and the error message names the cause.

Device 9999 does not exist, so the fix is to list the devices and use a real ID.

Worked example 3

A call returns 401 with the message token expired. The request itself is correct, so the fix is to get a new token and send it in the Authorization header. This is common with APIs whose tokens last for a fixed time.

Worked example 4

A script sends a body in a POST and receives 400. The error text says that the field name is required. The script sent title instead.

The documentation lists name as the correct field, so the field name is the bug.

Telling client faults from server faults

A 4xx code says that the fault is in the request. Repeating the same request gives the same error until you change it.

A 5xx code says the server failed. The same request may work later, so a retry with a growing delay is reasonable. You can still report it if the error persists.

Useful tools

• A command line client or API tool lets you send a request by hand and see the raw response.
• Printing response.status_code, response.headers and response.text in Python shows what came back.
• The API documentation's own try it out feature shows a request that is known to work.

response = requests.post(url, headers=headers, json=payload)
if not response.ok:
    print(response.status_code)
    print(response.text)