When working with external APIs, not every failure is caused by a bug in your code. Sometimes your code is completely correct, but the API has a limitation that you did not know about. These limitations can be especially difficult to find because the result may simply look like: the request did not work.

# My Experience With Telegram Bot API

Recently, I was working on a messaging system for a Telegram bot. The code looked correct, but some messages were not being sent. I checked my application logs and couldn’t find any obvious error. After checking the Telegram Bot API documentation more carefully, I found the problem. I was sending a photo with a caption, and the caption was longer than Telegram’s allowed limit. According to the Telegram Bot API documentation, photo captions can contain up to 1024 characters after entity parsing. The API limit was the problem, not my application logic.

# The Important Lesson

External APIs often have limits that are easy to overlook:

  • Maximum text length
  • Maximum file size
  • Maximum number of requests
  • Rate limits
  • Maximum number of items in an array
  • Required or restricted parameter values
  • Timeout limits
  • Pagination limits

A request can therefore look perfectly valid from your application’s perspective while still violating a restriction imposed by the API.

# Always Read the API Documentation

When working with an external API, don’t only look at the endpoint and its parameters. Check the documentation for the limitations and constraints of each parameter. For example, knowing that an API accepts a caption parameter is not enough. You also need to know whether that caption has a character limit. This is especially important when the data comes from users or a database, because its length may not be predictable.

# Add Your Own Validation

If an external API has a known limitation, don’t wait for the API to reject the request. Validate the data before sending it. This gives you a chance to:

  • Log the actual problem
  • Handle the data appropriately
  • Split long content into multiple messages
  • Return a meaningful error
  • Prevent unexpected API failures

The next time an external API call fails without an obvious explanation, check its documentation again.

The problem might not be your code. It might be a limit you didn’t know existed.