Vepler API Documentation

Overview

The Vepler API uses standard HTTP status codes and returns detailed error objects to help you handle errors gracefully. All errors follow a consistent structure for easy parsing and debugging.

Error Response Structure

All API errors return a JSON response with the following structure:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Property with ID 'p_0x999999' not found",
    "details": {
      "resource": "property",
      "id": "p_0x999999"
    },
    "request_id": "req_1234567890",
    "timestamp": "2024-03-20T14:30:00Z"
  }
}

Error Fields

Field	Type	Description
`code`	string	Machine-readable error code
`message`	string	Human-readable error message
`details`	object	Additional context about the error
`request_id`	string	Unique request identifier for support
`timestamp`	string	ISO 8601 timestamp of the error

HTTP Status Codes

Success Codes (2xx)

Status	Description	When Used
200 OK	Request succeeded	Successful GET, PUT, DELETE
201 Created	Resource created	Successful POST creating new resource
204 No Content	Request succeeded, no content	Successful DELETE

Client Error Codes (4xx)

Status	Error Code	Description
400 Bad Request	`INVALID_REQUEST`	Malformed request syntax or invalid parameters
401 Unauthorized	`UNAUTHORIZED`	Missing or invalid API key
403 Forbidden	`FORBIDDEN`	Valid API key but insufficient permissions
404 Not Found	`RESOURCE_NOT_FOUND`	Requested resource doesn’t exist
409 Conflict	`CONFLICT`	Request conflicts with current state
422 Unprocessable Entity	`VALIDATION_ERROR`	Request body validation failed
429 Too Many Requests	`RATE_LIMIT_EXCEEDED`	Rate limit exceeded

Server Error Codes (5xx)

Status	Error Code	Description
500 Internal Server Error	`INTERNAL_ERROR`	Unexpected server error
502 Bad Gateway	`GATEWAY_ERROR`	Upstream service error
503 Service Unavailable	`SERVICE_UNAVAILABLE`	Service temporarily unavailable
504 Gateway Timeout	`GATEWAY_TIMEOUT`	Upstream service timeout

Common Error Codes

Authentication Errors

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid",
    "details": {
      "header": "x-api-key",
      "key_prefix": "vpr_test_"
    }
  }
}

Code	Description	Solution
`MISSING_API_KEY`	No API key provided	Include `x-api-key` header
`INVALID_API_KEY`	API key is malformed or doesn’t exist	Check your API key
`EXPIRED_API_KEY`	API key has expired	Generate a new API key
`INSUFFICIENT_PERMISSIONS`	API key lacks required permissions	Upgrade plan or request access

Validation Errors

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "fields": [
        {
          "field": "latitude",
          "message": "Must be between -90 and 90",
          "value": 150
        },
        {
          "field": "radius",
          "message": "Must be positive number",
          "value": -100
        }
      ]
    }
  }
}

Code	Description	Solution
`VALIDATION_ERROR`	Request parameters invalid	Check field requirements
`INVALID_DATE_FORMAT`	Date format incorrect	Use ISO 8601 format
`INVALID_COORDINATES`	Lat/lng out of range	Verify coordinate values
`INVALID_POSTCODE`	UK postcode invalid	Check postcode format

Resource Errors

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Property not found",
    "details": {
      "resource": "property",
      "id": "p_0x999999",
      "suggestions": [
        "p_0x999998",
        "p_0x999997"
      ]
    }
  }
}

Code	Description	Solution
`RESOURCE_NOT_FOUND`	Resource doesn’t exist	Verify resource ID
`RESOURCE_DELETED`	Resource has been deleted	Resource no longer available
`RESOURCE_LOCKED`	Resource temporarily locked	Retry after delay

Rate Limiting Errors

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "API rate limit exceeded",
    "details": {
      "limit": 1000,
      "remaining": 0,
      "reset_at": "2024-03-20T15:00:00Z",
      "retry_after": 1800
    }
  }
}

Code	Description	Solution
`RATE_LIMIT_EXCEEDED`	Too many requests	Wait for reset or upgrade
`DAILY_QUOTA_EXCEEDED`	Daily limit reached	Wait until tomorrow or upgrade
`CONCURRENT_LIMIT_EXCEEDED`	Too many concurrent requests	Reduce parallel requests

Query Errors

{
  "error": {
    "code": "QUERY_TOO_BROAD",
    "message": "Query would return too many results",
    "details": {
      "estimated_results": 50000,
      "max_allowed": 10000,
      "suggestion": "Add more filters to narrow results"
    }
  }
}

Code	Description	Solution
`QUERY_TOO_BROAD`	Query returns too many results	Add more filters
`INVALID_QUERY_SYNTAX`	Query syntax incorrect	Check query format
`UNSUPPORTED_FILTER`	Filter not supported	Remove unsupported filter

Error Handling Examples

TypeScript/JavaScript

import { Vepler } from 'vepler-sdk';

const vepler = new Vepler({ apiKey: process.env.VEPLER_API_KEY });

async function getPropertySafely(id: string) {
  try {
    const property = await vepler.property.get(id);
    return property.data;
  } catch (error) {
    if (error.status === 404) {
      console.log('Property not found');
      return null;
    }

    if (error.status === 429) {
      const retryAfter = error.details?.retry_after || 60;
      console.log(`Rate limited. Retry after ${retryAfter} seconds`);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      return getPropertySafely(id); // Retry
    }

    if (error.status === 401) {
      console.error('Invalid API key');
      throw new Error('Authentication failed');
    }

    // Log unexpected errors
    console.error('Unexpected error:', error);
    throw error;
  }
}

Python

import time
from vepler import Vepler, VeplerError

client = Vepler(api_key=os.environ['VEPLER_API_KEY'])

def get_property_safely(property_id):
    try:
        property = client.property.get(property_id)
        return property.data
    except VeplerError as e:
        if e.status_code == 404:
            print(f"Property {property_id} not found")
            return None

        elif e.status_code == 429:
            retry_after = e.details.get('retry_after', 60)
            print(f"Rate limited. Waiting {retry_after} seconds...")
            time.sleep(retry_after)
            return get_property_safely(property_id)  # Retry

        elif e.status_code == 401:
            raise Exception("Invalid API key")

        else:
            print(f"Unexpected error: {e}")
            raise

cURL

#!/bin/bash

response=$(curl -s -w "\n%{http_code}" \
  -H "x-api-key: $VEPLER_API_KEY" \
  "https://api.vepler.com/v1/property/p_0x000123456789")

body=$(echo "$response" | head -n -1)
status=$(echo "$response" | tail -n 1)

if [ "$status" -eq 200 ]; then
  echo "Success: $body"
elif [ "$status" -eq 404 ]; then
  echo "Property not found"
elif [ "$status" -eq 429 ]; then
  retry_after=$(echo "$body" | jq -r '.error.details.retry_after')
  echo "Rate limited. Retry after $retry_after seconds"
  sleep "$retry_after"
elif [ "$status" -eq 401 ]; then
  echo "Authentication failed"
  exit 1
else
  echo "Error $status: $body"
  exit 1
fi

Retry Strategy

Implement exponential backoff for transient errors:

async function retryWithBackoff(
  fn: () => Promise<any>,
  maxRetries = 3,
  baseDelay = 1000
) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      // Don't retry client errors (except 429)
      if (error.status >= 400 && error.status < 500 && error.status !== 429) {
        throw error;
      }

      if (i === maxRetries - 1) throw error;

      const delay = baseDelay * Math.pow(2, i);
      console.log(`Retry ${i + 1}/${maxRetries} after ${delay}ms`);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

// Usage
const property = await retryWithBackoff(() =>
  vepler.property.get('p_0x000123456789')
);

Error Recovery Patterns

Circuit Breaker

Prevent cascading failures:

class CircuitBreaker {
  private failures = 0;
  private lastFailTime = 0;
  private state: 'CLOSED' | 'OPEN' | 'HALF_OPEN' = 'CLOSED';

  constructor(
    private threshold = 5,
    private timeout = 60000
  ) {}

  async execute<T>(fn: () => Promise<T>): Promise<T> {
    if (this.state === 'OPEN') {
      if (Date.now() - this.lastFailTime > this.timeout) {
        this.state = 'HALF_OPEN';
      } else {
        throw new Error('Circuit breaker is OPEN');
      }
    }

    try {
      const result = await fn();
      if (this.state === 'HALF_OPEN') {
        this.state = 'CLOSED';
        this.failures = 0;
      }
      return result;
    } catch (error) {
      this.failures++;
      this.lastFailTime = Date.now();

      if (this.failures >= this.threshold) {
        this.state = 'OPEN';
      }
      throw error;
    }
  }
}

Graceful Degradation

Provide fallback behavior:

async function getPropertyWithFallback(id: string) {
  try {
    // Try to get fresh data
    const property = await vepler.property.get(id);
    cache.set(id, property.data);
    return property.data;
  } catch (error) {
    // Fall back to cache if available
    const cached = cache.get(id);
    if (cached) {
      console.warn('Using cached data due to error:', error.message);
      return cached;
    }

    // Return partial data if appropriate
    if (error.status === 503) {
      return {
        id,
        status: 'unavailable',
        message: 'Property data temporarily unavailable'
      };
    }

    throw error;
  }
}

Debugging

Use the request_id for support requests:

try {
  const property = await vepler.property.get('p_0x000123456789');
} catch (error) {
  console.error(`Error (Request ID: ${error.request_id}):`, error.message);

  // When contacting support, provide:
  // 1. Request ID
  // 2. Timestamp
  // 3. Error code
  // 4. Endpoint called
}

Best Practices

Always Handle Errors

Never assume API calls will succeed:

// ❌ Bad
const property = await vepler.property.get(id);
console.log(property.address);

// ✅ Good
try {
  const property = await vepler.property.get(id);
  console.log(property.address);
} catch (error) {
  handleError(error);
}

Log Errors Properly

Include context in error logs:

logger.error('Property fetch failed', {
  propertyId: id,
  errorCode: error.code,
  errorMessage: error.message,
  requestId: error.request_id,
  timestamp: new Date().toISOString()
});

Use Specific Error Handlers

Handle different errors appropriately:

function handleApiError(error) {
  switch (error.code) {
    case 'RESOURCE_NOT_FOUND':
      return { found: false };
    case 'RATE_LIMIT_EXCEEDED':
      return scheduleRetry(error.details.retry_after);
    case 'VALIDATION_ERROR':
      return { valid: false, errors: error.details.fields };
    default:
      throw error;
  }
}

Implement Timeouts

Set reasonable timeouts:

const property = await Promise.race([
  vepler.property.get(id),
  new Promise((_, reject) =>
    setTimeout(() => reject(new Error('Timeout')), 5000)
  )
]);

Getting Started

Error Handling

Overview

Error Response Structure

Error Fields

HTTP Status Codes

Success Codes (2xx)

Client Error Codes (4xx)

Server Error Codes (5xx)

Common Error Codes

Authentication Errors

Validation Errors

Resource Errors

Rate Limiting Errors

Query Errors

Error Handling Examples

TypeScript/JavaScript

Python

cURL

Retry Strategy

Error Recovery Patterns

Circuit Breaker

Graceful Degradation

Debugging

Best Practices

Next Steps

Rate Limiting

SDK Examples

Getting Started

​Overview

​Error Response Structure

​Error Fields

​HTTP Status Codes

​Success Codes (2xx)

​Client Error Codes (4xx)

​Server Error Codes (5xx)

​Common Error Codes

​Authentication Errors

​Validation Errors

​Resource Errors

​Rate Limiting Errors

​Query Errors

​Error Handling Examples

​TypeScript/JavaScript

​Python

​cURL

​Retry Strategy

​Error Recovery Patterns

​Circuit Breaker

​Graceful Degradation

​Debugging

​Best Practices

​Next Steps

Rate Limiting

SDK Examples

Overview

Error Response Structure

Error Fields

HTTP Status Codes

Success Codes (2xx)

Client Error Codes (4xx)

Server Error Codes (5xx)

Common Error Codes

Authentication Errors

Validation Errors

Resource Errors

Rate Limiting Errors

Query Errors

Error Handling Examples

TypeScript/JavaScript

Python

cURL

Retry Strategy

Error Recovery Patterns

Circuit Breaker

Graceful Degradation

Debugging

Best Practices

Next Steps