Best practices

This is some advice on best practices for using the API, regardless of your particular use case. Follow this advice for less errors and better performance.

• Use RequestId Every failed API request has RequestId property in the Error response details. We highly recommend to include this information in your observability solution. Provide this value when contacting support.

• Handling HTTP status codes Follow our recommendations on handling each response code and how to resolve most common issues.

• Webhooks instead of polling Instead of periodically polling for updates using a 'get' operation, use Webhooks instead and subscribe to updates. Contact support if a Webhook for an event is not supported . For more information, see Ways to communicate.

• Limit use of extents Limit the amount of extents you use as much as possible. You can see an example of extents in Get all resources. An extent represents a related entity that requires lookup into another database table, thus significantly hindering performance. If you need to use multiple extents, instead create a separate call for each individual extent.

• Use pagination Use pagination for 'get' operations wherever possible. Responses will be smaller and easier to manage, and you won't hit those request timeouts!

• Use filtering Avoid retrieving the same data repetitively. Leverage filtering to retrieve just the subset of data that's relevant to you. Data past the Editable History Window can't be changed so it doesn't make sense to pull it repeatedly. If there is no support for a filter you'd benefit from, contact support with a request to add it.

• Cache data and limit high-traffic calls Querying for static or frequently needed data on every request adds unnecessary traffic and slows down the user experience. Cache data that don't change often (e.g. resource categories, services, products, accounting categories, business segments, configuration, taxes). For high-traffic or get-all style endpoints (availability, restrictions, pricing), don't call on every page view, refresh, or keystroke. Cache responses (e.g. 30–60 seconds for search-like data), filter to the minimal scope, use pagination, and apply client-side rate limiting and exponential backoff when you see increased latency or errors.

• Graceful degradation and resiliency Assume that API calls can be slow, fail, or be throttled, resulting in error responses, timeouts or blocking. Degrade only the affected feature (e.g. availability refresh), not the whole product. Fail fast in interactive flows and retry in the background with exponential backoff. See request limits.

• Respect shared capacity The API is multi-tenant: your traffic shares capacity with other properties and partners. Implement client-side rate limiting and backoff so that you don't keep sending requests when you receive 429 or see increased latency. Mews rate limiting protects the system, but your integration should avoid hitting it in the first place. Proactively monitor your traffic volume and resolve client-side issues before they escalate. Stay within documented limits. If your usage will change significantly, coordinate with Mews in advance so we can anticipate load and help avoid impact on your integration and others.

• Planned campaigns and traffic spikes When planning activities resulting in substantially higher traffic (e.g. marketing campaigns, bulk operations), inform Mews via your partner contact or contact support with the planned time window, expected traffic multiplier, and affected endpoints, so we're aware in case something goes wrong and have a quick contact point. We do not offer increased rate limits; ensure your integration fits within request limits and handles being rate limited. Your integration should use caching, exponential backoff, rate limiting, and circuit breakers in place.

• Consequences of not following best practices Integrations that repeatedly ignore basic best practices (for example, continuing to send requests at high volume after being rate limited) may be blocked by Mews to protect our systems and other users.