Skip to main content
placeanalyzerAPI ReferenceGuías

Error Handling

Even the best integrations can fail. This guide helps you identify, understand, and resolve errors in the Place Analyzer API.

HTTP Status Codes

The API uses standard HTTP status codes. Here are the most common ones:

CodeNameDescriptionRetry?
200OKSuccessful request❌ No
201CreatedResource created successfully❌ No
400Bad RequestInvalid data in the request❌ No (correct data)
401UnauthorizedInvalid or missing API Key❌ No (correct API Key)
404Not FoundResource not found❌ No (verify URLs)
429Too Many RequestsRate limit exceeded✅ Yes (with backoff)
500Internal Server ErrorInternal server error✅ Yes (temporary)

Error Response Structure

All errors follow a consistent JSON structure:

{
  "errorCode": "VALIDATION_ERROR",
  "message": "Legible description of the error",
  "details": {
    "field": "property.propertyType",
    "provided": "INVALID",
    "expected": ["Terreno", "Casa", "Duplex", "Departamento", "Deposito", "Tinglado", "Oficina", "Local Comercial", "Propiedad rural", "Casa quinta", "Edificio"]
  },
  "timestamp": "2025-01-15T10:30:00Z",
  "requestId": "req-123456"
}

Important fields:

  • errorCode: Specific error code (see catalog below)
  • message: Description of the error
  • details: Additional information for debugging
  • timestamp: When the error occurred
  • requestId: Unique ID for technical support

Error Code Catalog

🔐 Authentication Errors

INVALID_API_KEY

  • Description: The provided API Key is invalid
  • Common cause: Misspelled or expired API Key
  • Solution: Verify API Key in the dashboard
{
  "errorCode": "INVALID_API_KEY",
  "message": "The provided API Key is invalid",
  "details": {
    "providedKey": "xxx",
    "expectedFormat": "PA-XXXX-XXXX"
  }
}

MISSING_API_KEY

  • Description: No API Key was provided
  • Common cause: Missing header
  • Solution: Include -H "X-API-KEY: your_api_key"

API_KEY_EXPIRED

  • Description: The API Key has expired
  • Common cause: Old key
  • Solution: Generate a new key in the dashboard

INSUFFICIENT_PERMISSIONS

  • Description: The API Key does not have permissions for this operation
  • Common cause: Sandbox key used in production
  • Solution: Verify environment (sandbox vs production)

✅ Validation Errors

VALIDATION_ERROR

  • Description: Invalid data in the request
  • Common cause: Missing fields or incorrect format
  • Solution: Review and correct the data sent
{
  "errorCode": "VALIDATION_ERROR",
  "message": "Validation errors in the request",
  "details": {
    "errors": [
      {
        "field": "latitude",
        "message": "Value must be between -90 and 90",
        "provided": 91
      },
      {
        "field": "property.propertyType",
        "message": "Must be one of: Terreno, Casa, Duplex, Departamento, Deposito, Tinglado, Oficina, Local Comercial, Propiedad rural, Casa quinta, Edificio",
        "provided": "INVALID"
      },
      {
        "field": "property.m2Covered",
        "message": "El área cubierta (m2Covered) es requerida para Departamentos"
      }
    ]
  }
}

Common validation fields:

Coordinates:

  • latitude: must be between -90 and 90
  • longitude: must be between -180 and 180

Property:

  • propertyType: must be one of the allowed values (Terreno, Casa, Duplex, Departamento, Deposito, Tinglado, Oficina, Local Comercial, Propiedad rural, Casa quinta, Edificio)
  • m2Land, m2Built, m2Covered, m2SemiCovered: when sent, must be >= 0
  • Requiredness of m2Land, m2Built, m2Covered, m2SemiCovered, propertyAge, and propertyCondition depends on propertyType (see Individual Appraisals)

Required-field messages by type:

  • Terreno: "El área del terreno (m2Land) es requerida para Terrenos"
  • Departamento: "El área cubierta (m2Covered) es requerida para Departamentos", "El área semicubierta (m2SemiCovered) es requerida para Departamentos", "La antigüedad (propertyAge) es requerida para Departamentos"
  • Other types: "El área del terreno (m2Land) es requerida", "El área construida (m2Built) es requerida", "La antigüedad (propertyAge) es requerida", "El estado de conservación (propertyCondition) es requerido"

🔍 Resource Not Found Errors

REQUEST_NOT_FOUND

  • Description: The requestCode does not exist
  • Common cause: Misspelled requestCode or it never existed
  • Solution: Verify that the requestCode is correct
{
  "errorCode": "REQUEST_NOT_FOUND",
  "message": "The request with the provided code was not found",
  "details": {
    "providedCode": "PA-2025-INVALID",
    "suggestion": "Verify that the code is correct"
  }
}

RESULT_NOT_AVAILABLE

  • Description: The result is not available yet
  • Common cause: Valuation still in process (PENDING_PROCESSING)
  • Solution: Wait and check again
{
  "errorCode": "RESULT_NOT_AVAILABLE",
  "message": "The result is not available yet",
  "details": {
    "requestCode": "PA-2025-001234",
    "currentStatus": "PENDING_PROCESSING",
    "suggestion": "Wait for the status to be COMPLETED"
  }
}

PROPERTY_NOT_FOUND

  • Description: The property does not exist
  • Common cause: Invalid propertyId
  • Solution: Verify the propertyId

📊 Rate Limiting Errors

RATE_LIMIT_EXCEEDED

  • Description: You have exceeded the request limit
  • Common cause: Too many queries in a short time
  • Solution: Implement exponential backoff
{
  "errorCode": "RATE_LIMIT_EXCEEDED",
  "message": "You have exceeded the request limit per minute",
  "details": {
    "currentLimit": 100,
    "requestsInWindow": 105,
    "resetTime": "2025-01-15T10:31:00Z",
    "retryAfter": 60
  }
}

🖥️ Server Errors

INTERNAL_SERVER_ERROR

  • Description: Internal server error
  • Common cause: Temporary server issues
  • Solution: Retry with exponential backoff

SERVICE_UNAVAILABLE

  • Description: Service temporarily unavailable
  • Common cause: Maintenance or overload
  • Solution: Retry later

Error Handling Strategies

1. Smart Retries

class ApiClient {
  async request(url, options, maxRetries = 3) {
    for (let attempt = 1; attempt <= maxRetries; attempt++) {
      try {
        const response = await fetch(url, options);

        if (response.ok) {
          return response.json();
        }

        const error = await response.json();

        // Do not retry validation errors
        if (response.status === 400 || response.status === 401 || response.status === 404) {
          throw new Error(`${error.errorCode}: ${error.message}`);
        }

        // Retry server errors
        if (attempt === maxRetries) {
          throw new Error(`Error after ${maxRetries} attempts: ${error.message}`);
        }

        // Exponential backoff
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));

      } catch (error) {
        if (attempt === maxRetries) {
          throw error;
        }
      }
    }
  }
}

2. Specific Error Handling

async function handleValuationRequest(requestData, apiKey) {
  try {
    const response = await apiClient.post('/valuation-request', requestData, apiKey);
    return response;
  } catch (error) {
    switch (error.message.split(':')[0]) {
      case 'VALIDATION_ERROR':
        console.log('Invalid data:', error.details);
        // Show correction form
        break;

      case 'INVALID_API_KEY':
        console.log('Invalid API Key, redirecting to login');
        // Redirect to login page
        break;

      case 'RATE_LIMIT_EXCEEDED':
        console.log('Rate limit exceeded, showing wait message');
        // Show wait message
        break;

      default:
        console.log('Unexpected error:', error.message);
        // Generic error
    }
  }
}

3. Logging and Monitoring

class ErrorLogger {
  static logError(error, context = {}) {
    const errorInfo = {
      timestamp: new Date().toISOString(),
      errorCode: error.errorCode,
      message: error.message,
      details: error.details,
      context: context,
      userAgent: navigator.userAgent,
      url: window.location.href
    };

    // Send to logging service
    console.error('API Error:', errorInfo);

    // In production, send to service like Sentry
    // Sentry.captureException(error, { extra: errorInfo });
  }
}

Practical Examples

Rate Limiting Handling

async function handleRateLimit() {
  const response = await fetch('/api/valuation-request', {
    headers: { 'X-API-KEY': API_KEY }
  });

  if (response.status === 429) {
    const error = await response.json();
    const resetTime = new Date(error.details.resetTime);
    const waitTime = resetTime.getTime() - Date.now();

    console.log(`Rate limit exceeded. Wait ${Math.ceil(waitTime / 1000)} seconds`);

    await new Promise(resolve => setTimeout(resolve, waitTime));
    return await makeRequest(); // Retry
  }
}

Validation before sending

function validateValuationRequest(data) {
  const errors = [];
  const property = data.property || {};

  if (data.latitude == null || data.latitude < -90 || data.latitude > 90) {
    errors.push({ field: 'latitude', message: 'Must be between -90 and 90' });
  }

  if (data.longitude == null || data.longitude < -180 || data.longitude > 180) {
    errors.push({ field: 'longitude', message: 'Must be between -180 and 180' });
  }

  const validTypes = [
    'Terreno', 'Casa', 'Duplex', 'Departamento', 'Deposito', 'Tinglado',
    'Oficina', 'Local Comercial', 'Propiedad rural', 'Casa quinta', 'Edificio'
  ];
  if (!property.propertyType || !validTypes.includes(property.propertyType)) {
    errors.push({
      field: 'property.propertyType',
      message: `Must be one of: ${validTypes.join(', ')}`
    });
  }

  // Conditional fields by propertyType (examples):
  // Terreno → m2Land
  // Departamento → m2Covered, m2SemiCovered, propertyAge
  // Other types → m2Land, m2Built, propertyAge, propertyCondition

  return errors;
}

Monitoring and Alerts

Important metrics to monitor:

  1. Error rate per endpoint
  2. Average response time
  3. Rate limits reached
  4. Authentication errors

Example dashboard:

// Send metrics to your monitoring system
function trackApiMetrics(endpoint, status, responseTime, errorCode = null) {
  analytics.track('api_request', {
    endpoint: endpoint,
    status: status,
    responseTime: responseTime,
    errorCode: errorCode,
    timestamp: new Date().toISOString()
  });
}

Technical Support

If you cannot resolve an error:

  1. Save the requestId from the error response
  2. Include the requestId in your support query
  3. Provide the code you are using
  4. Describe what you expected to happen
// Example of a complete error report
const errorReport = {
  requestId: error.requestId,
  timestamp: error.timestamp,
  endpoint: '/valuation-request',
  method: 'POST',
  status: 400,
  errorCode: error.errorCode,
  userAgent: navigator.userAgent,
  requestData: requestData // Without API Key!
};

Conclusion

Proactive error handling improves user experience and reduces technical support. Implement:

  • ✅ Client-side validation before sending
  • ✅ Smart retries for temporary errors
  • ✅ Detailed logging for debugging
  • ✅ Friendly error messages for users
  • ✅ Monitoring of error metrics

Still having problems? See our glossary of statuses and terms or contact support with your requestId.