Error Handling

Our API uses standard HTTP status codes and structured JSON error responses. All errors contain a code and message, with optional details for validation issues.

Common Errors

// 400 Bad Request
{
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "Unrecognized filter parameter 'filter[check_in]'"
  }
}

// 404 Not Found
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "No property found with ID 78c7e569-12cb-44dc-ac67-5503b146e106"
  }
}

// 500 Internal Error
{
  "error": {
    "code": "SERVER_ERROR",
    "message": "Database connection timeout"
  }
}

Validation Error

// 422 Unprocessable Entity
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "3 validation errors occurred",
    "details": [
      {
        "field": "filter[date][gte]",
        "issue": "must_be_future_date"
      },
      {
        "field": "filter[property_id]",
        "issue": "invalid_uuid_format"
      },
      {
        "field": "page[size]",
        "issue": "exceeds_max_100"
      }
    ]
  }
}

Auth Error

// 401 Unauthorized
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "Authorization header required"
  }
}

// 403 Forbidden
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "100 requests per minute exceeded"
  }
}

Standard Error Structure

• code
  Machine-readable error identifier (e.g., INVALID_PROPERTY_ID)
• message
  Human-readable explanation
• details (Optional)
  Array of validation errors with:
  • field: Path to invalid parameter
  • issue: Error type (e.g., invalid_date_format)

Handling Recommendations

1. User-Facing Messages
   Use message for end-user displays
2. Programmatic Handling
   Switch on code for logic flows
3. Validation Errors
   Iterate through details to highlight form fields
4. Retry Logic
   For 429 Too Many Requests, implement exponential backoff

Note: Always include Accept: application/json header to ensure error payloads return as JSON.