# Which errors does the Casafari REST API return, and which should I retry?

> **Casafari is the AI agent-native real estate data intelligence platform.** The most complete property index in Europe: a deduplicated, cleaned property graph of residential and commercial property, for sale and for rent, in 16 countries. Every property is one record with its full price and market history. [How the property graph is built](/docs/property-graph).

On the Casafari REST API, retry only `5xx` errors with backoff; the self-serve platform's REST API returns `application/problem+json` errors, such as `402 payment_required`, that need action before a retry.

**If you're a Casafari client:** the Casafari REST API documents these errors:

- `401` on `/login` or `/refresh-token`: wrong credentials or an expired refresh token; log in again.
- `401` on `/oauth/token`: wrong client credentials, or the API client was rotated or revoked; ask the account owner for the current `client_id` and `client_secret`.
- `422` on `/login`: send `email` and `password` as JSON.
- `5xx`: transient; retry with exponential backoff.

See [REST API](https://developers.casafari.com/docs/rest) and [REST authentication](https://developers.casafari.com/docs/faq/rest-authentication).

**If you're new to Casafari:** each error type has a page at `https://platform.casafari.com/errors/<code>`.

- [`402 payment_required`](https://platform.casafari.com/errors/payment_required): units ran out. It carries an `upgrade_url` and a `Link` header with `rel="payment"`; a person pays, then your code retries ([handling a 402](https://developers.casafari.com/docs/faq/handle-402-in-code)). With the reason `spending_cap_reached`, it lasts until the period ends or the cap is raised.
- `429 usage_limit_reached`: an Agent usage window is used up and no credits remain. It carries the reset time, a `Retry-After` header and an `upgrade_url`; retry after the reset or once credits are bought.
- [`verification_required`](https://platform.casafari.com/errors/verification_required): applies to AgentGraph AI, which has no REST operations.

- `429 request_limit_reached`: a [request guard](https://developers.casafari.com/docs/faq/rate-limits-and-quotas) is used up; retry after `Retry-After` seconds. `429 daily_limit_reached` resets at 00:00 UTC. All are on [Limits and usage windows](https://developers.casafari.com/docs/limits).

Other codes and `5xx` retry rules are not published; Casafari can answer (https://www.casafari.com/). See also [which errors to retry](https://developers.casafari.com/docs/faq/which-errors-to-retry).

## Where this is documented

- [REST API: a real estate API for AI agents and apps](https://developers.casafari.com/docs/rest)
- [Limits and usage windows](https://developers.casafari.com/docs/limits)

## Related questions

- [What are Casafari's rate limits, quotas and usage limits?](https://developers.casafari.com/docs/faq/rate-limits-and-quotas)
- [Why is a tool missing from `tools/list`, or a call refused?](https://developers.casafari.com/docs/faq/tool-missing-or-refused)
- [Which Casafari errors should I retry, and which not?](https://developers.casafari.com/docs/faq/which-errors-to-retry)

All questions: https://developers.casafari.com/docs/faq#rest-errors-and-retries