Errors

The Prop AI Deals API uses standard HTTP status codes. Every error response has the same JSON shape so your error handler only needs to be written once.

Error response format

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 1.0 seconds.",
    "retry_after": 1.0
  }
}

error.code — Stable machine-readable string. Switch on this in code.
error.message — Human-readable explanation. Show in UI / log to console.
Additional fields — Some errors include extra context (e.g. retry_after, required_scope).

HTTP status codes

Status	Meaning
`200`	Success
`400`	Malformed request — fix and retry
`401`	Authentication failed — check your API key
`403`	Authenticated, but key lacks the required scope
`404`	Resource not found
`422`	Validation error — request body or query params invalid
`429`	Rate limit or quota exceeded — back off and retry
`500`	Internal server error — usually transient, retry with backoff
`502`	Upstream bad gateway — retry
`503`	Service temporarily unavailable — retry with backoff

Error codes

`invalid_api_key` — 401

The Authorization header is missing, malformed, or the key has been revoked / expired.

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid or expired API key"
  }
}

Fix: Verify the header is exactly Authorization: Bearer paid_.... Check the key hasn’t been revoked in the dashboard.

`insufficient_scope` — 403

Your key is valid, but its plan doesn’t grant access to this endpoint.

{
  "error": {
    "code": "insufficient_scope",
    "message": "This key lacks the required scope: ai:chat"
  }
}

Fix: Upgrade your plan, or use a different endpoint. See Authentication › Scopes.

`rate_limit_exceeded` — 429

You’re sending requests faster than your plan’s per-second limit allows.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 1.0 seconds.",
    "retry_after": 1.0
  }
}

Fix: Sleep for retry_after seconds and retry. Implement client-side throttling. See Rate limits.

`monthly_quota_exceeded` — 429

You’ve reached your plan’s hard monthly request limit. There is no 2× soft/hard split — once you hit the number printed in X-Monthly-Limit, every subsequent request is rejected until the next calendar month rolls over.

{
  "error": {
    "code": "monthly_quota_exceeded",
    "message": "Monthly request quota exceeded (250000/250000). Upgrade your plan or wait until the next billing period.",
    "used": 250000,
    "limit": 250000
  }
}

This error is NOT transient. Do not retry with backoff — retries will fail with the same error until the billing period resets. Fix: Upgrade your plan at /dashboard/api (takes effect immediately after Stripe charges succeed), or wait until the first of next month when usage counters reset.

`ai_chat_quota_exceeded` — 429

AI chat endpoints (/api/v1/ultimate-ai/*) have a separate monthly quota that’s been used up.

{
  "error": {
    "code": "ai_chat_quota_exceeded",
    "message": "AI chat quota exceeded (100/100). Upgrade your plan or wait until the next billing period.",
    "used": 100,
    "limit": 100
  }
}

Every paid tier includes AI chat: Starter 100/month, Professional 1,000/month, Business 4,000/month. Fix: Upgrade for a higher AI chat quota, or wait until the first of next month when usage counters reset. Non-AI endpoints continue to work normally until your main monthly quota is also exhausted.

`endpoint_not_in_public_api` — 403

You tried to call an internal endpoint (like /api/v1/api-keys or /api/v1/dashboard/*) with a paid_* API key. The public API exposes only the routes listed in the API reference — dashboard and billing endpoints require a Clerk session token, not an API key.

{
  "error": {
    "code": "endpoint_not_in_public_api",
    "message": "The endpoint /api/v1/dashboard/stats is not exposed via API key authentication."
  }
}

Fix: Check the supported endpoint list. If you need the requested endpoint exposed publicly, email info@propaideals.co.uk.

`Service temporarily busy` — 503

The API server rejected your request because its database connection pool was at >85% capacity. This is a protective fast-fail under high concurrent load, not a quota or auth error.

{
  "error": "Service temporarily busy",
  "detail": "Database connection pool at capacity. Please retry.",
  "retry_after": 2
}

The response includes a Retry-After: 2 header. 503s do not count against your monthly quota — we only charge successful handler executions. Fix: Retry after retry_after seconds with exponential backoff. If you see sustained 503s, you’re pushing concurrent load higher than your plan’s capacity — throttle client-side.

`validation_error` — 422

The request body or query string failed validation.

{
  "error": {
    "code": "validation_error",
    "message": "Invalid value for 'min_price': must be a positive integer",
    "details": {
      "field": "min_price",
      "value": "-100"
    }
  }
}

Fix: Check the endpoint reference for valid field types and ranges.

`not_found` — 404

The resource ID doesn’t exist or has been deleted.

{
  "error": {
    "code": "not_found",
    "message": "Property not found: 5fa1b2c3-d4e5-6f78-9012-3456789abcde"
  }
}

Fix: Check the ID. Property IDs are UUIDs.

`internal_error` — 500

Something went wrong on our side. We’re already alerted.

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred. Please try again."
  }
}

Fix: Retry with exponential backoff. If it persists, contact support with your meta.request_id.

Recommended retry policy

Implement exponential backoff with jitter for 429, 500, 502, and 503. Don’t retry 400, 401, 403, 404, or 422 — they will fail the same way every time.

async function callApi(url, options, attempt = 0) {
  const res = await fetch(url, options)
  if (res.ok) return res.json()

  const body = await res.json().catch(() => ({}))
  const code = body.error?.code

  // Don't retry client errors
  if (res.status >= 400 && res.status < 500 && res.status !== 429) {
    throw new Error(`${code}: ${body.error?.message}`)
  }

  // Retry with backoff
  if (attempt >= 5) {
    throw new Error(`Max retries exceeded: ${code}`)
  }

  const retryAfter = body.error?.retry_after ?? Math.pow(2, attempt)
  const jitter = Math.random() * 0.3
  await new Promise(r => setTimeout(r, (retryAfter + jitter) * 1000))
  return callApi(url, options, attempt + 1)
}

import time, random, requests

def call_api(url, headers, attempt=0):
    res = requests.get(url, headers=headers, timeout=15)
    if res.ok:
        return res.json()

    body = res.json() if res.headers.get("content-type", "").startswith("application/json") else {}
    code = body.get("error", {}).get("code")

    # Don't retry client errors
    if 400 <= res.status_code < 500 and res.status_code != 429:
        raise RuntimeError(f"{code}: {body.get('error', {}).get('message')}")

    if attempt >= 5:
        raise RuntimeError(f"Max retries exceeded: {code}")

    retry_after = body.get("error", {}).get("retry_after", 2 ** attempt)
    time.sleep(retry_after + random.uniform(0, 0.3))
    return call_api(url, headers, attempt + 1)

Getting help

Every response includes a unique meta.request_id. Include it when you contact support:

Subject: API request failing
Request ID: req_8c7f2a1b9d4e3f5a
Error code: internal_error
Endpoint: GET /api/v1/properties?area=London
Time: 2026-04-14T10:23:00Z

Email: info@propaideals.co.uk

Get started

API reference

Granular endpoints

Resources

Errors

Errors

Error response format

HTTP status codes

Error codes

`invalid_api_key` — 401

`insufficient_scope` — 403

`rate_limit_exceeded` — 429

`monthly_quota_exceeded` — 429

`ai_chat_quota_exceeded` — 429

`endpoint_not_in_public_api` — 403

`Service temporarily busy` — 503

`validation_error` — 422

`not_found` — 404

`internal_error` — 500

Recommended retry policy

Getting help

​Errors

​Error response format

​HTTP status codes

​Error codes

​invalid_api_key — 401

​insufficient_scope — 403

​rate_limit_exceeded — 429

​monthly_quota_exceeded — 429

​ai_chat_quota_exceeded — 429

​endpoint_not_in_public_api — 403

​Service temporarily busy — 503

​validation_error — 422

​not_found — 404

​internal_error — 500

​Recommended retry policy

​Getting help

Errors

Error response format

HTTP status codes

Error codes

`invalid_api_key` — 401

`insufficient_scope` — 403

`rate_limit_exceeded` — 429

`monthly_quota_exceeded` — 429

`ai_chat_quota_exceeded` — 429

`endpoint_not_in_public_api` — 403

`Service temporarily busy` — 503

`validation_error` — 422

`not_found` — 404

`internal_error` — 500

Recommended retry policy

Getting help