Api Troubleshooting

Deep API Troubleshooting Guide

Goal

API troubleshooting is about finding where the failure is happening:

Client/App → Network → API Gateway → Authentication → Backend Service → Database/External System

A good implementation engineer isolates the layer before escalating.

1. Start With 4 Basic Questions

Question	Why It Matters
What is expected to happen?	Defines success
What actually happens?	Defines the failure
Is it reproducible?	Separates one-time issue from systemic issue
Who is affected?	Helps identify scope

Example:

Expected: CRM ticket is created after chat ends.
Actual: Chat ends, but no CRM ticket appears.
Scope: One customer environment, all agents.

2. Identify the API Direction

Direction	Meaning	Example
Inbound API	Customer system calls platform API	CRM calls Glia API
Outbound API	Platform calls customer system	Glia calls CRM API
Webhook	Event notification sent automatically	Chat ended → CRM ticket
Callback	Response sent after async process	Payment status update

This matters because it tells you which side to check first.

3. Check the HTTP Method

Method	Troubleshooting Focus
GET	Is the resource ID correct?
POST	Is the payload valid?
PUT	Are all required fields included?
PATCH	Are updated fields allowed?
DELETE	Does the user/token have delete permission?

Example issue:

GET /api/create-ticket

But the API expects:

POST /api/create-ticket

Likely result:

405 Method Not Allowed

4. Check the Endpoint

Validate:

Base URL
API version
Path
Resource ID
Query parameters
Environment

Example:

https://api.vendor.com/v1/customers/12345

Common mistakes:

Problem	Example
Wrong environment	Using sandbox instead of production
Wrong API version	`/v1/` instead of `/v2/`
Typo in endpoint	`/costumers/` instead of `/customers/`
Missing resource ID	`/customers/` instead of `/customers/12345`

5. Check Headers

Important headers:

Header	Purpose
Authorization	Sends bearer token/API key
Content-Type	Format of request body
Accept	Format expected in response
x-api-key	API key authentication
Correlation-ID	Request tracking

Example:

Authorization: Bearer eyJhbGc...
Content-Type: application/json
Accept: application/json

Common issue:

Content-Type missing

API may not understand the JSON body.

6. Check Authentication

Most API failures happen here.

Error	Meaning	Common Cause
401	Not authenticated	Missing/expired/invalid token
403	Authenticated but blocked	Missing permission/scope/role

401 Checklist

Check:

Is Authorization header present?
Is token expired?
Is token copied correctly?
Is token for the right environment?
Was token revoked?

403 Checklist

Check:

Does token have correct scope?
Does user/app have permission?
Is IP allowlisting required?
Is this endpoint restricted?

7. Check OAuth Scope

Scopes define what the token can do.

Example:

read:customers
write:tickets
admin

If token only has:

read:customers

but you call:

POST /api/tickets

You may get:

403 Forbidden

8. Check the JSON Payload

For POST/PUT/PATCH, inspect payload carefully.

Example:

{
  "customerId": "12345",
  "channel": "chat",
  "authenticated": true
}

Validate:

Item	Example Problem
Syntax	Missing comma
Required fields	Missing customerId
Data type	`"true"` instead of `true`
Field name	`customerID` instead of `customerId`
Nesting	Object expected, string sent
Array format	Single value sent instead of list

9. Understand Status Codes by Category

Code Range	Meaning
2xx	Success
3xx	Redirect
4xx	Client/request issue
5xx	Server/backend issue

Important Codes

Code	Meaning	First Place To Look
200	Success	Validate response body
201	Created	Confirm resource ID returned
204	No Content	Success, but no body
400	Bad Request	Payload/parameters
401	Unauthorized	Authentication
403	Forbidden	Permissions/scopes
404	Not Found	Endpoint/resource
405	Method Not Allowed	HTTP method
408	Timeout	Network/backend delay
409	Conflict	Duplicate/existing resource
415	Unsupported Media Type	Content-Type
422	Validation error	Field validation
429	Rate limit	Too many requests
500	Server error	Backend logs
502	Bad gateway	Proxy/upstream
503	Unavailable	Outage/maintenance
504	Gateway timeout	Backend too slow

10. Troubleshooting by Error Code

400 Bad Request

Likely:

Invalid payload, missing fields, wrong query parameter

Check:

JSON syntax
Required fields
Field names
Data types
API documentation

401 Unauthorized

Likely:

Authentication failed

Check:

Token present
Token expired
Correct auth method
Correct environment

403 Forbidden

Likely:

Permission issue

Check:

User role
OAuth scopes
API permissions
IP allowlist

404 Not Found

Likely:

Wrong endpoint or resource does not exist

Check:

URL path
API version
Resource ID
Environment

409 Conflict

Likely:

Duplicate or conflicting resource

Example:

Trying to create a user that already exists

415 Unsupported Media Type

Likely:

Wrong or missing Content-Type

Check:

Content-Type: application/json

422 Validation Error

Likely:

Payload is valid JSON but fails business rules

Example:

Phone number format invalid
Required field has invalid value

429 Too Many Requests

Likely:

Rate limit exceeded

Check:

Retry-After header
API rate limits
Looping automation
Retry logic

500 Internal Server Error

Likely:

Backend application error

Action:

Collect request ID, timestamp, payload sample, and escalate

502 / 503 / 504

Likely:

Gateway, service availability, or timeout issue

Check:

Load balancer
API gateway
Backend health
Maintenance window
Network latency

11. Network Layer Checks

APIs depend on network reachability.

Check:

DNS resolution
Firewall
Proxy
Port 443
TLS certificate
IP allowlisting
VPN/private connectivity

Common symptoms:

Symptom	Possible Cause
Timeout	Firewall, proxy, backend delay
TLS error	Certificate or TLS mismatch
DNS failure	Wrong hostname
Connection refused	Service down or port blocked

12. TLS / Certificate Checks

For HTTPS APIs, validate:

Certificate not expired
Hostname matches certificate
Certificate chain trusted
TLS 1.2 or 1.3 supported

Common failures:

certificate expired
self-signed certificate
hostname mismatch
TLS handshake failed

13. Rate Limiting

Rate limiting protects APIs from overload.

Common response:

429 Too Many Requests

Check headers:

Retry-After: 60

Troubleshooting:

Reduce request frequency
Add backoff/retry logic
Check if automation is looping
Review API quota

14. Timeouts

Timeouts can occur at multiple layers:

Client timeout
API gateway timeout
Load balancer timeout
Backend service timeout
Database timeout

Ask:

How long before failure?
Does it fail always or intermittently?
Is payload large?
Is backend dependency slow?

15. Correlation IDs

A correlation ID tracks one request across systems.

Example:

X-Correlation-ID: abc-123

Use it to trace:

API Gateway → Auth Service → Backend Service → Database

For escalation, always include:

correlation ID
timestamp
endpoint
HTTP method
response code

16. Logs To Review

Log Type	What It Shows
API Gateway logs	Request entry, routing, response code
Auth logs	OAuth/token failures
Application logs	Backend errors
Webhook logs	Delivery attempts
Load balancer logs	Upstream health/timeouts
Firewall/proxy logs	Blocked connections
CRM logs	Customer/ticket integration failures

17. Good Troubleshooting Workflow

1. Confirm expected behavior
2. Reproduce issue
3. Identify endpoint + method
4. Check response code
5. Validate auth
6. Validate headers
7. Validate payload
8. Validate network/TLS
9. Check logs/correlation ID
10. Isolate failed layer
11. Escalate with evidence

18. Example Scenario

Issue

Chat ends but CRM ticket is not created.

Expected Flow

Chat completed → Webhook sent → CRM API creates ticket

Troubleshooting

Check:

Was chat_completed event generated?
Was webhook sent?
Did CRM receive webhook?
What HTTP response did CRM return?
Was token valid?
Was JSON payload accepted?
Was ticket required field missing?

Possible findings:

Finding	Meaning
No event generated	Platform workflow issue
Webhook sent, no response	CRM endpoint/network issue
401 from CRM	Auth/token issue
400 from CRM	Payload/field mapping issue
500 from CRM	CRM backend issue

19. Another Scenario

Issue

Customer lookup fails during chat start.

Expected Flow

Customer enters → API calls CRM → CRM returns profile

Check:

Customer ID passed correctly?
CRM endpoint correct?
Token valid?
Customer exists?
Field mapping correct?
CRM API response code?

Likely outcomes:

Response	Likely Issue
401	Token expired
403	Missing CRM permission
404	Customer not found
400	Bad customerId format
500	CRM backend failure

20. What To Say In Interview