Key Takeaways
- An error code is the stable, machine-readable part of a failure; the message is for humans and may change.
- HTTP status codes describe the request class (4xx your side, 5xx theirs); platform codes in the body say exactly what failed.
- 429 means slow down: honour Retry-After rather than retrying immediately.
- Handle errors by code, log the full body, and keep a lookup for the platforms you use.
What Is an Error Code?
An error code is a short value that a program, API or device returns to say what went wrong. It is designed to be stable and machine-readable, so your code can branch on it - retry, ask the user to log in again, skip a deleted record - while the accompanying error message explains the problem to a person.
Codes come in two layers when you call a web API. The HTTP status code describes the class of failure, and many platforms add their own code in the response body that pins down the exact cause.
HTTP Status Codes vs Platform Error Codes
| Range | Meaning | Common examples |
|---|---|---|
| 2xx | Success | 200 OK, 201 Created, 204 No Content |
| 3xx | Redirect | 301 Moved Permanently, 304 Not Modified |
| 4xx | The request was wrong | 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 429 Too Many Requests |
| 5xx | The server failed | 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout |
Inside the body, platforms are more specific. Discord returns a numeric code such as 50013 Missing Permissions; Telegram returns error_code plus a description like Bad Request: chat not found; WhatsApp's Cloud API returns a Graph error with code and error_subcode; Slack answers HTTP 200 with "ok": false and a string such as channel_not_found. Two failures with the same HTTP status can need completely different fixes, which is why the body matters.
How to Read an Error Response
- Log the whole body, not just the status. The platform code and message live there.
- Check the class. A 4xx means change the request - credentials, permissions, parameters. A 5xx or timeout means retry later.
- Respect rate limits. On 429, wait for the time in
Retry-After(or the platform'sretry_afterfield) before trying again. Immediate retries extend the block. - Look the code up. Our error code directory explains causes and fixes for WhatsApp, Telegram, Discord, Messenger, Instagram, Slack, LINE and Teams, and the limits pages list the quotas behind most 429s.
Designing Good Error Codes
If you build an API or a bot backend, good error codes are cheap to add and save hours later:
- Keep codes stable and documented; never reuse one for a different meaning.
- Return the right HTTP class as well as your own code, so generic clients behave sensibly.
- Pair every code with a message a developer can act on, and a link to its documentation.
- Distinguish retryable failures from permanent ones explicitly.
Error Codes in Chatbots
A chatbot calls several APIs on every message: the messaging channel, often an AI model, and your own systems through webhooks. Most "the bot stopped answering" incidents trace back to one error code - an expired token (401), a removed permission (403), a blocked user (403 on Telegram), or a rate limit (429). Logging them per channel turns a mystery into a one-line fix. Hosted platforms such as a website chatbot handle the retries and alerting for you.
Frequently Asked Questions
What is an error code in simple terms?
What is the difference between an error code and an error message?
What do 4xx and 5xx error codes mean?
What should I do with a 429 error code?
Where can I look up Telegram, Discord or WhatsApp error codes?
Free plan, no credit card required.