Skip to main content

​
Error Format

All errors follow a consistent format: 
{
  "error": {
    "type": "validation_error",
    "title": "Invalid request parameters",
    "status": 400,
    "detail": "Request validation failed",
    "trace_id": "trace_abc123"
  },
  "metadata": {
    "request_id": "req_xyz789"
  }
}
FieldDescription
typeMachine-readable error type
titleHuman-readable error title
statusHTTP status code
detailDetailed error description
trace_idIdentifier for debugging (include when contacting support)

​
Validation Errors

Validation errors include an errors array with field-specific details: 
{
  "error": {
    "type": "validation_error",
    "title": "Invalid request parameters",
    "status": 422,
    "detail": "Request validation failed",
    "trace_id": "trace_abc123",
    "errors": [
      {
        "field": "email",
        "message": "Invalid email format",
        "code": "INVALID_FORMAT"
      },
      {
        "field": "limit",
        "message": "Must be between 1 and 100",
        "code": "OUT_OF_RANGE"
      }
    ]
  },
  "metadata": {
    "request_id": "req_xyz789"
  }
}

​
Status Codes

All endpoints may return these error responses:
StatusTypeDescription
400bad_requestInvalid request parameters
401unauthorizedInvalid or expired token
403forbiddenInsufficient permissions
404not_foundResource doesn’t exist
422validation_errorRequest body validation failed
429rate_limit_exceededToo many requests
500internal_errorServer error - contact support

​
Handling Errors

const response = await fetch('https://api.village.do/v2/people/search', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ query: 'john doe' })
});

if (!response.ok) {
  const errorData = await response.json();
  
  switch (errorData.error.status) {
    case 401:
      // Token expired, refresh and retry
      break;
    case 429:
      // Rate limited, implement backoff
      break;
    case 422:
      // Validation error, check errorData.error.errors
      break;
    default:
      // Log trace_id for debugging
      console.error('API Error:', errorData.error.trace_id);
  }
}