Handle API errors and rate limits

The Middesk API uses HTTP status codes to indicate whether a request succeeded. Use the status code and response body to decide whether to correct the request or retry it.

Status codes

Codes in the 2xx range indicate success. Codes in the 4xx range indicate a request or access problem. Codes in the 5xx range indicate a server error.

Error messages

Most API errors return JSON with an errors array. Each error contains a message and can include a parameter identifying the affected field. Rate-limited requests can return plain text instead; check the 429 response formats before parsing the body as JSON.

{
  "errors": [
    {
      "message": "Name is required",
      "parameter": "name"
    },
    {
      "message": "Address line1 is required",
      "parameter": "address.address_line1"
    }
  ]
}

Rate limits

Middesk tracks most limits by credential. Each API key and OAuth access token has its own limits, so your sandbox and Production keys do not share them. Requests that exceed a limit return 429 Too Many Requests.

Default limit

Requests to /v1/ endpoints share a limit of 20 requests per second for each credential, except autocomplete, which has separate limits below.

Endpoint-specific limits

Your frontend usually sends autocomplete requests with the same Publishable API key, so all end users share that key’s limit.

Sandbox business creation limit

In sandbox, each account can create up to 120 businesses per minute. These requests share the limit:

• POST /v1/businesses
• The createBusiness GraphQL mutation
• POST /v1/business_batches, where each batch row counts as one business

The limit resets at the start of each minute. Contact your account manager to raise this sandbox limit.

Handling 429 responses

The response format depends on the limit exceeded:

import random
import time
import requests
def request_with_retry(method, url, max_attempts=5, **kwargs):
    if max_attempts < 1:
        raise ValueError("max_attempts must be at least 1")
    kwargs.setdefault("timeout", 30)
    delay = 1
    for attempt in range(1, max_attempts + 1):
        response = requests.request(method, url, **kwargs)
        if response.status_code != 429 or attempt == max_attempts:
            return response
        retry_after = response.headers.get("Retry-After")
        time.sleep(float(retry_after) if retry_after else delay + random.uniform(0, delay))
        delay *= 2

Reducing request volume

• Use webhooks to learn when a business changes instead of polling GET /v1/businesses/{id}.
• Use business batches to create many businesses in one request. In sandbox, each row still counts toward the business creation limit.
• Combine changes to the same business into one PATCH request.