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:
| Code | Name | Description | Retry? |
|---|---|---|---|
200 | OK | Successful request | ❌ No |
201 | Created | Resource created successfully | ❌ No |
400 | Bad Request | Invalid data in the request | ❌ No (correct data) |
401 | Unauthorized | Invalid or missing API Key | ❌ No (correct API Key) |
404 | Not Found | Resource not found | ❌ No (verify URLs) |
429 | Too Many Requests | Rate limit exceeded | ✅ Yes (with backoff) |
500 | Internal Server Error | Internal 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 errordetails: Additional information for debuggingtimestamp: When the error occurredrequestId: 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 90longitude: 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, andpropertyConditiondepends onpropertyType(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:
- Error rate per endpoint
- Average response time
- Rate limits reached
- 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:
- Save the
requestIdfrom the error response - Include the
requestIdin your support query - Provide the code you are using
- 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.