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`, then distinguish subscription `RateLimit-` from report `X-RateLimit-`
`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

Immoteur returns application/problem+json Problem Details for 400, 401, 422, default application errors, and 429 from POST /public/v1/issues. That public issue-report 429 has code rate_limited. Record the traceId from the response body and the X-Trace-Id header when Immoteur emits them. 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 subscription-quota 429 responses, the body is application/json with { "message": "Too Many Requests" }. The RateLimit-* header values are ordered by second, minute, then day; read them instead of hard-coding example values. POST /public/v1/issues uses independent report counters for each authenticated user. Its per-second and per-minute maximums match the current data-access plan, while its daily maximum is the lower of the plan’s daily maximum and 2,500. Report attempts neither debit nor depend on ordinary subscription quota, so ordinary quota exhaustion does not prevent reporting.

Read rate-limit and diagnostic headers

The following headers describe subscription quota on ordinary data endpoints. They do not describe the independent report allowance for POST /public/v1/issues.

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

The public issue-report endpoint uses endpoint-throttle headers instead.

Header	Behavior	Client action
`X-RateLimit-Limit`	Current report limit enforced by the endpoint	Read it from the response instead of deriving a fixed limit from a plan
`X-RateLimit-Remaining`	Requests still available for the reported endpoint limit	Slow down before it reaches zero
`Retry-After`	Delay before retrying a rejected report or subscription-quota request	Do not send the next request before this delay expires
`X-RateLimit-Reset`	Unix timestamp when a rejected report can be retried	Use it with `Retry-After` to schedule the retry
`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

For ordinary subscription-quota endpoints, 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