Status Codes

RealtyAPI uses standard HTTP status codes to indicate the success or failure of API requests.

Quick Reference

CodeName
200OK
400Bad Request
401Unauthorized
403Forbidden
404Not Found
429Too Many Requests
500Internal Server Error
502Bad Gateway
503Service Unavailable

Detailed Breakdown

200OK

The request was successful and the response contains the requested data.

{ "success": true, "data": { ... } }
400Bad Request

The request was malformed or missing required parameters.

{ "error": "Missing required parameter: address" }
401Unauthorized

The API key is missing, invalid, or expired.

{ "error": "Invalid API key" }
403Forbidden

The API key does not have permission to access this resource.

{ "error": "Access denied to this endpoint" }
404Not Found

The requested resource could not be found.

{ "error": "Property not found" }
429Too Many Requests

You have exceeded the rate limit. Wait before making more requests.

{ "error": "Rate limit exceeded", "retryAfter": 60 }
500Internal Server Error

An unexpected error occurred on our servers. Please try again later.

{ "error": "Internal server error" }
502Bad Gateway

The upstream service is temporarily unavailable.

{ "error": "Service temporarily unavailable" }
503Service Unavailable

The service is undergoing maintenance or is temporarily overloaded.

{ "error": "Service unavailable" }

Error Handling Best Practices

1

Check the status code first

Always check the HTTP status code before processing the response body.

2

Parse error messages

The response body will contain a detailed error message explaining what went wrong.

3

Implement retry logic

For 5xx errors, implement exponential backoff and retry the request.

4

Handle 429 gracefully

If rate limited, check the Retry-After header and wait before retrying.

5

Log errors for debugging

Log error responses to help diagnose issues in your integration.