API reliability: errors and rate limits

Handle every response by status code and content type. Do not treat a failed response as a successful result.

Handle the response

Outcome	Action
`2xx`	Process the documented response body
`400`	Read the Problem Details response, correct the malformed request, then send a new request
`401`	Check the API token and Bearer authentication configuration, then obtain or use a valid token
`403`	Confirm that the token has access to the resource before sending a new request
`409`	Use the supplied configuration URL or dashboard to configure data access, then send a new request
`404`	Confirm the identifier or URL lookup target; do not retry an unchanged request
`422`	Correct the invalid request input identified by the validation response, then send a new request
`429`	Wait for `Retry-After` before the next request, then inspect the rate-limit headers
`503`	Wait for the `Retry-After` delay, then retry
Other `5xx` or network errors	Retry with bounded backoff and retain any available trace ID

Distinguish response bodies and diagnostics

For 400, 401, 422, and default application errors, Immoteur returns application/problem+json Problem Details. Record the traceId from the response body and the X-Trace-Id header when Immoteur emits them. Use the details to correct the request or access configuration rather than retrying unchanged input. For 403 and 404, verify the token’s access or the requested identifier and lookup target before sending a new request. Do not assume a particular response body or trace header for these responses. For 409, Immoteur returns application/json with a message, configurationUrl, and documentationUrl. Follow the configuration URL or open API → Data Access in the Immoteur dashboard to configure the missing data access, then send a new request. Do not expect Problem Details or a trace ID for this response. For 429, the body is application/json with { "message": "Too Many Requests" }. 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.

Read rate-limit and diagnostic headers

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`	Delay to wait after a rate limit or limiter-outage response	Do not send the next request before this delay expires
`X-Trace-Id`	Trace ID attached to Problem Details when emitted by Immoteur	Save it with the request context when investigating a failure

Retry temporary failures safely

A 503 limiter outage uses application/json with { "message": "Rate limit service unavailable" } and a Retry-After delay. Honor the delay before retrying; the current outage response uses one second. For other transient 5xx responses or network failures, use a bounded backoff and retry policy. Log any available trace IDs, status code, and request context so that a failed retry can be investigated. Do not retry 400, 401, 403, 409, 404, or 422 until you have taken the corrective action above. 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

Distinguish response bodies and diagnostics

Read rate-limit and diagnostic headers

Retry temporary failures safely

​Handle the response

​Distinguish response bodies and diagnostics

​Read rate-limit and diagnostic headers

​Retry temporary failures safely

Handle the response

Distinguish response bodies and diagnostics

Read rate-limit and diagnostic headers

Retry temporary failures safely