API reliability: errors and rate limits

Handle API responses from their status code and problem-details body. Do not treat a failed response as a successful result.

Handle the response

Outcome	Action
`2xx`	Process the documented response body
`401`	Check the API token and Bearer authentication configuration
`403`, `404`, or `422`	Read the `application/problem+json` response and correct access, the identifier, or request input
`429`	Wait for `Retry-After` before sending the next request, then inspect the rate-limit headers
Support investigation	Record `X-Trace-Id` with the request context

Read rate-limit and diagnostic headers

The rate-limit header values are ordered by second, minute, then day. Limits depend on your subscription, so read the response instead of hard-coding example values.

Header	Behavior	Client action
`RateLimit-Policy`	Describes the active windows, for example a limit with its window duration	Use it to interpret the matching values in the remaining rate-limit headers
`RateLimit-Limit`	Maximum requests in each active second, minute, and day window	Plan throughput from the response, not from a fixed documentation value
`RateLimit-Remaining`	Requests still available in each window	Slow down before the smallest remaining window reaches zero
`RateLimit-Reset`	Seconds until each current window resets	Use it to decide when capacity becomes available again
`Retry-After`	Seconds to wait after `429 Too Many Requests`	Do not send the next request before this delay expires
`X-Trace-Id`	Correlation ID attached to problem responses	Save it with the request context when contacting Immoteur support

Use curl --include while integrating to inspect both headers and the response body:

curl --include --show-error --silent \
  'https://api.immoteur.com/public/v1/auth' \
  -H "Authorization: Bearer $IMMOTEUR_TOKEN"

For token and data-access setup, see API tokens and data access. For endpoint-specific errors, use the generated API reference.

Start

API

Webhooks

OpenAPI reference

API reliability: errors and rate limits

Handle the response

Read rate-limit and diagnostic headers

​Handle the response

​Read rate-limit and diagnostic headers

Handle the response

Read rate-limit and diagnostic headers