Error Handling

Error Response Format

All errors follow a consistent format:

{
  "error": {
    "code": "invalid_request",
    "message": "The 'email' field is required.",
    "field": "email",
    "doc_url": "https://proptechusa.ai/docs/api/errors#invalid_request"
  }
}

HTTP Status Codes

Code	Meaning

200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limited
500	Internal Server Error

Error Codes

Authentication Errors

Code	Description

invalid_api_key	API key is invalid or expired
missing_api_key	No API key provided
insufficient_permissions	Key lacks required permissions

Validation Errors

Code	Description

invalid_request	Request body is malformed
missing_field	Required field not provided
invalid_field	Field value is invalid

Resource Errors

Code	Description

not_found	Resource doesn't exist
already_exists	Resource already exists
conflict	Resource state conflict

Error Handling Example

try {
  const lead = await proptech.leads.create({
    email: 'invalid-email',
  });
} catch (error) {
  if (error instanceof PropTechError) {
    switch (error.code) {
      case 'invalid_field':
        console.log(Invalid field: ${error.field});
        break;
      case 'rate_limit_exceeded':
        // Retry after delay
        break;
      default:
        console.error(error.message);
    }
  }
}