Core Concepts

Copy page

Errors & Troubleshooting

When something goes wrong, the FairePlace API returns structured error responses with enough detail to diagnose and fix the issue.

Error response format

Every error follows this structure:

Code
 
{
  "error": {
    "code": 422,
    "type": "VALIDATION_ERROR",
    "message": "Invalid lease data",
    "details": {
      "field": "rent_amount",
      "message": "Rent amount must be greater than 0"
    }
  },
  "meta": {
    "request_id": "req_7f3a8b2c-1d4e-5f60-a7b8-c9d0e1f23456",
    "timestamp": "2026-02-19T10:30:00Z"
  }
}

Field	Description
error.code	HTTP status code
error.type	Machine-readable error type (e.g., VALIDATION_ERROR, NOT_FOUND)
error.message	Human-readable description
error.details	Additional context (field names, constraints, etc.)
meta.request_id	Unique request identifier — include this when contacting support
meta.timestamp	When the error occurred

HTTP status codes

Code	Type	When it happens
400	Bad Request	Malformed JSON, invalid UUID format, missing required fields
401	Unauthorized	Missing, expired, or malformed JWT token
403	Forbidden	Valid token but insufficient permissions
404	Not Found	Resource doesn't exist or belongs to another tenant
409	Conflict	Cannot delete resource with dependencies (e.g., place with estates)
422	Unprocessable Entity	Valid JSON but business rule violation (e.g., rent exceeds cap)
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error — contact support with request_id

Common errors and fixes

400 — Invalid UUID format

Code
 
{
  "error": {
    "code": 400,
    "type": "BAD_REQUEST",
    "message": "Invalid UUID format for field 'estate_id'",
    "details": {
      "field": "estate_id",
      "value": "not-a-uuid"
    }
  }
}

Fix: Use a valid UUID v4 format: 550e8400-e29b-41d4-a716-446655440000.

400 — Missing required field

Code
 
{
  "error": {
    "code": 400,
    "type": "VALIDATION_ERROR",
    "message": "Missing required fields",
    "details": [
      { "field": "name", "message": "Name is required" },
      { "field": "owner_id", "message": "Owner ID is required" }
    ]
  }
}

Fix: Check the API module documentation for required fields.

401 — Token expired

Code
 
{
  "error": {
    "code": 401,
    "type": "UNAUTHORIZED",
    "message": "Token expired"
  }
}

Fix: Re-authenticate with POST /auth/login and use the new token.

403 — Permission denied

Code
 
{
  "error": {
    "code": 403,
    "type": "FORBIDDEN",
    "message": "Permission 'leases:write' required"
  }
}

Fix: Your token is missing the required permission. See Authentication for the full permissions table.

404 — Resource not found

Code
 
{
  "error": {
    "code": 404,
    "type": "NOT_FOUND",
    "message": "Lease not found"
  }
}

Common causes:

• The UUID is wrong or has a typo
• The resource belongs to a different tenant (cross-tenant access returns 404, not 403)
• The resource was deleted

409 — Dependency conflict

Code
 
{
  "error": {
    "code": 409,
    "type": "CONFLICT",
    "message": "Cannot delete place with associated estates"
  }
}

Fix: Remove dependent resources first. For example, delete all estates in a place before deleting the place itself.

422 — Rent cap violation

Code
 
{
  "error": {
    "code": 422,
    "type": "COMPLIANCE_ERROR",
    "message": "Rent exceeds legal maximum for this legislative zone",
    "details": {
      "rule": "RentCap",
      "current_value": 28.00,
      "maximum_allowed": 25.50,
      "unit": "EUR/m2"
    }
  }
}

Fix: The rent per square meter exceeds the reference rent (loyer de reference majore) for the property's legislative zone. Lower the rent amount or check if a rent complement (complement de loyer) applies.

422 — Deposit limit exceeded

Code
 
{
  "error": {
    "code": 422,
    "type": "COMPLIANCE_ERROR",
    "message": "Deposit exceeds legal maximum",
    "details": {
      "rule": "DepositLimit",
      "current_value": 2000.00,
      "maximum_allowed": 950.00,
      "explanation": "Deposit cannot exceed 1 month rent for unfurnished residential leases"
    }
  }
}

Fix: French law limits the security deposit to 1 month's rent (excluding charges) for unfurnished leases, and 2 months for furnished leases.

429 — Rate limit exceeded

Code
 
{
  "error": {
    "code": 429,
    "type": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "details": {
      "limit": 1000,
      "window": "1 hour",
      "retry_after": 847
    }
  }
}

Fix: Wait until the rate limit resets. Check these response headers:

Header	Description
X-RateLimit-Limit	Maximum requests per hour (1,000)
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when the window resets
Retry-After	Seconds to wait before retrying (on 429 responses)

Retry strategy

For transient errors (429, 500), use exponential backoff:

Code
 
async function apiCall(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get("Retry-After") || 60;
      await sleep(retryAfter * 1000);
      continue;
    }

    if (response.status >= 500) {
      await sleep(Math.pow(2, attempt) * 1000); // 1s, 2s, 4s
      continue;
    }

    return response;
  }
  throw new Error("Max retries exceeded");
}

Do not retry 400, 401, 403, 404, 409, or 422 errors — these require fixing the request.

Debugging checklist

When you get an unexpected error:

1. Check the request_id — Include it when contacting support
2. Verify your token — Is it expired? Decode it at jwt.io to check exp and permissions
3. Check the tenant_id — Are you targeting the right organization?
4. Validate UUIDs — Ensure all IDs are valid UUID v4 format
5. Review required fields — Check the API module docs for the endpoint you're calling
6. Check dependencies — Does the parent resource exist? (e.g., does the estate_id exist before creating a lease?)
7. Inspect the full error — The details field often tells you exactly what to fix