Response Codes

The Realie Property Data API returns the following response codes to indicate the status of your requests and potential errors that may arise.

Only successful 200 responses spend a token from your monthly allowance. Empty results (404), authentication failures (401), and access denials (403, including billing and spending-limit blocks) are not billed.

{ 
  "properties": {} 
}
//Success

{ 
  "error": "Bad Request" 
}
//Bad Request - Missing or invalid parameters.

{ 
  "error": "Unauthorized: API key is missing" 
}
//Unauthorized: API key is missing/invalid.

{
  "error": "Forbidden: Pay your outstanding invoices to restore access",
  "code": "unpaid_invoices",
  "action": "Open Billing and pay all outstanding invoices. Update your payment card if a payment fails, then retry once your subscription is active.",
  "billing_url": "https://app.realie.ai/billing"
}
//Forbidden: Resolve the reason in code before retrying.

{ 
  "error": "No properties not found" 
}
//No properties found fitting search criteria

{ 
  "error": "Too many requests" 
}
//Rate Limit Exceeded: 1200 calls per minute maximum

{ 
  "error": "Internal Server Error" 
}
//Internal Server Error. If you continue to experience this issue, please contact support

{ 
  "error": "Server timed out" 
}
//Gateway Timeout

Resolving a 403 response

A 403 does not always mean you have used your token allowance. Billing, card verification, subscription status, and your overage spending cap can also block a request. Public data API access denials include these fields:

Field	Meaning
`error`	A human-readable explanation. Wording can vary by plan and account state.
`code`	The machine-readable reason. Use this field, rather than matching `error` text, to handle the denial in your integration.
`action`	The next step to restore access. Display this guidance to the person who manages billing.
`billing_url`	A link to Billing, where the account owner can resolve the issue.

`code`	Meaning and next step
`card_not_verified`	No eligible card is available because verification is incomplete or a card was declined. Complete verification in Billing. Wait if it is still running; if it failed, follow the recovery instructions or add a card that can accept charges.
`payment_method_required`	Add a payment card in Billing and complete its verification.
`overage_limit_exceeded`	Your overage spending cap blocks this request. Raise or remove the cap in Billing, or wait for the next billing period. Raising or removing the cap permits additional charges.
`unpaid_invoices`	Pay all outstanding invoices, including older invoices. Update your card if payment fails. Contact support if an invoice cannot be paid in Billing.
`subscription_inactive`	Your subscription is not active. Review Billing, pay outstanding invoices, and complete activation or reactivate your plan as applicable. Retry once the subscription is active and the other access requirements are met.
`subscription_required`	Activate a subscription with a payment card in Billing. Contact support if you already have a subscription.
`subscription_ended`	Your subscription period has ended. Reactivate your plan or choose a subscription in Billing.
`billing_unavailable`	We could not confirm billing access. Follow `action`: retry briefly when instructed, or contact support if the issue persists. Changing your card or spending cap is not required.
`billing_configuration_error`	We could not validate your plan’s billing configuration. Contact support; this is not a spending-limit overrun.
`access_denied`	Review Billing and the returned `action`. Contact support if the reason is unclear.

The response reports the first blocking condition, not every issue on the account. A past_due or unpaid subscription can return subscription_inactive before an unpaid balance would return unpaid_invoices. Paying only the latest invoice is not enough if older invoices remain unpaid. Access requires an active subscription, an eligible payment card, no outstanding invoice debt, and sufficient allowance or overage capacity.

After resolving the issue, allow billing updates to complete before retrying. Repeating a request without fixing a card, invoice, or subscription problem will continue to return 403. See the billing recovery FAQ for the payment and card-verification steps. Each response code includes an example JSON payload to help identify the issue and guide your next steps. If you are experiencing issues please contact support@realie.ai for assistance.

Get Started

Response Fields & Types

Property

Premium

Resolving a 403 response

​Resolving a 403 response

Resolving a 403 response