Error Handling and Rate Limits

The OpenTiendas API provides clear error messages and rate limits to help you build robust and reliable integrations.

Error Handling

The API uses conventional HTTP status codes to indicate the outcome of each request.
They are typically grouped into:

• 2xx — Successful operations
• 4xx — Client-side errors (e.g., invalid parameters or missing data)
• 5xx — Server-side errors (e.g., internal issues or temporary unavailability)

Below is a summary of common response codes:

Code	Summary	Description
200	OK	The request completed successfully.
201	Created	A new resource was created successfully.
204	No Content	The request was successful, but there is no content in the response body.
400	Bad Request	Missing required parameters or invalid values in the request.
403	Forbidden	Valid credentials, but insufficient permissions for the requested operation.
404	Not Found	The requested resource does not exist.
405	Method Not Allowed	The HTTP method is not supported for the requested resource.
429	Too Many Requests	You’ve exceeded the rate limit for this endpoint.
500	Internal Server Error	A server-side issue occurred while processing the request.

Example error response

If the API key is invalid or has been disabled, you might receive:

{
  "detail": "API key disabled"
}

Best practices for error handling

• Check the HTTP status code and error message in each response.
• Use retry logic with backoff (e.g., exponential backoff), especially for 5xx errors.
• Avoid retrying 4xx errors (except 429); fix issues like invalid API keys before retrying.
• Log errors for debugging and monitoring.

Rate Limits

The current OpenTiendas API rate limits are:

• Up to 2 requests per second
• Up to 2,000 requests per day

If you exceed these limits, the API will respond with HTTP 429 Too Many Requests.

tip

To request a higher rate limit, please reach out to your OpenTiendas provider

Best practices to avoid reaching limits

• Use caching and batching to reduce unnecessary requests.
• Optimize request efficiency during peak loads.

Idempotency

Future versions of the OpenTiendas API will support idempotency keys for operations such as order creation and updates. This will ensure that repeated requests with the same key produce the same result, preventing duplicates.

Once implemented, developers will be able to:

• Include an idempotency key in requests to safely retry operations.
• Ensure requests are idempotent, avoiding unintended side effects.

Scaling considerations

• Use asynchronous processing and queues to handle high request volumes.
• Monitor API usage, errors, and performance.

---

Proactively handling errors and limits keeps your integration stable and reliable.
For sample code, see the Sample Code section.