BayutAPI

Error Reference

A complete reference of HTTP error codes returned by BayutAPI, with common causes and recommended fixes for each.

Overview

BayutAPI uses standard HTTP status codes to indicate the success or failure of a request. Codes in the 2xx range indicate success, 4xx codes indicate a client error, and 5xx codes indicate a server-side issue. All error responses are returned as JSON.

Quick Reference

Code Name
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
429 Too Many Requests
500 Internal Server Error
502 Bad Gateway / Service Unavailable
400

Bad Request

Common Causes

  • A required parameter is missing from the request
  • A parameter value has an invalid format (e.g., non-numeric page number)
  • An enum parameter has an unrecognized value (e.g., invalid sort_order)
  • The query string is malformed or contains unsupported characters

How to Fix

  • Check the endpoint documentation for all required parameters
  • Validate parameter types before sending the request (e.g., ensure page is a number)
  • Use only allowed values for enum parameters like sort_order, completion_status, and is_furnished
  • URL-encode special characters in query parameters

Example Response

400 Bad Request 
{
  "success": false,
  "message": "Invalid request: Missing required parameter 'purpose'",
  "error": "VALIDATION_ERROR"
}
401

Unauthorized

Common Causes

  • The x-rapidapi-key header is missing from the request
  • The API key is invalid, expired, or revoked
  • The x-rapidapi-host header is missing or incorrect

How to Fix

  • Include both x-rapidapi-key and x-rapidapi-host headers in every request
  • Verify your API key in the RapidAPI dashboard — regenerate it if necessary
  • Ensure x-rapidapi-host is set to bayut14.p.rapidapi.com exactly
  • Check that your API key has no extra whitespace or newline characters

Example Response

401 Unauthorized 
{
  "message": "Missing RapidAPI application key. Go to https://docs.rapidapi.com/ to learn how to get your API application key."
}
403

Forbidden

Common Causes

  • Your RapidAPI account is not subscribed to BayutAPI
  • Your subscription has been suspended due to payment failure
  • You are trying to access an endpoint not included in your current plan

How to Fix

  • Subscribe to a BayutAPI plan on RapidAPI (free tier available)
  • Check your RapidAPI billing settings and update your payment method
  • Upgrade your subscription plan if required

Example Response

403 Forbidden 
{
  "message": "You are not subscribed to this API."
}
404

Not Found

Common Causes

  • The endpoint URL path is misspelled or does not exist
  • The requested resource ID (e.g., external_id, agent_id) does not match any record
  • A trailing slash or incorrect path segment was included in the URL

How to Fix

  • Double-check the endpoint path against the API documentation
  • Verify that resource IDs are valid — use search endpoints to find correct IDs first
  • Remove trailing slashes from endpoint URLs
  • Ensure the base URL is https://bayut14.p.rapidapi.com

Example Response

404 Not Found 
{
  "success": false,
  "message": "Resource not found",
  "error": "NOT_FOUND"
}
429

Too Many Requests

Common Causes

  • You have exceeded the monthly request quota for your RapidAPI plan
  • You are sending requests faster than your plan's rate limit allows
  • Multiple applications are sharing the same API key and collectively exceeding the limit

How to Fix

  • Check your current usage in the RapidAPI dashboard
  • Upgrade to a higher plan for more requests (Pro: 10,000/mo, Ultra: 50,000/mo, Mega: 100,000/mo)
  • Implement request caching to reduce redundant API calls
  • Add exponential backoff retry logic in your application
  • Use separate API keys for different applications if needed

Example Response

429 Too Many Requests 
{
  "message": "You have exceeded the MONTHLY quota for requests on your current plan. Upgrade your plan at https://rapidapi.com/happyendpoint/api/bayut14/pricing"
}
500

Internal Server Error

Common Causes

  • An unexpected error occurred on the API server
  • A temporary issue with the upstream data source
  • A bug in the API processing logic (rare)

How to Fix

  • Retry the request after a short delay (1-2 seconds)
  • If the error persists, check the BayutAPI status page or RapidAPI status
  • Contact support if the error continues for more than 15 minutes
  • Include the full error response when reporting issues

Example Response

500 Internal Server Error 
{
  "success": false,
  "message": "Internal server error. Please try again later.",
  "error": "INTERNAL_ERROR"
}
502

Bad Gateway / Service Unavailable

Common Causes

  • The upstream data source is temporarily down for maintenance
  • A network issue between the API server and the data provider
  • High traffic causing temporary service degradation

How to Fix

  • Wait 30-60 seconds and retry the request
  • Implement retry logic with exponential backoff (e.g., 1s, 2s, 4s, 8s)
  • Check the BayutAPI status page for any ongoing incidents
  • If building a production app, add fallback behavior for when the API is unavailable

Example Response

502 Bad Gateway / Service Unavailable 
{
  "success": false,
  "message": "Service temporarily unavailable. Please try again later.",
  "error": "API_ERROR"
}

Handling Errors Gracefully

For production applications, implement retry logic with exponential backoff for transient errors (429, 500, 502). This example shows a reusable retry wrapper in JavaScript:

Retry with Exponential Backoff 
async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429 || response.status >= 500) {
      const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
      console.log(`Retrying in ${delay}ms (attempt ${attempt + 1})`);
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

    return response;
  }

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