Error Codes

Complete reference for all error codes in OAF-100.

Standard Error Response Format

All errors follow this structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": { /* Optional additional context */ }
  }
}

General Error Codes

Code	HTTP Status	Description
INVALID_REQUEST	400	The request is malformed or missing required fields
VALIDATION_ERROR	400	Request data failed validation
AUTHENTICATION_FAILED	401	Missing or invalid authentication credentials
FORBIDDEN	403	Valid credentials but insufficient permissions
RESOURCE_NOT_FOUND	404	The requested resource does not exist
METHOD_NOT_ALLOWED	405	HTTP method not supported for this endpoint
CONFLICT	409	Request conflicts with current state
INTERNAL_ERROR	500	Unexpected server error
SERVICE_UNAVAILABLE	503	Service temporarily unavailable

Location-Specific Error Codes

Code	HTTP Status	Description
INVALID_COORDINATES	400	Latitude or longitude values are out of valid range
INVALID_ADDRESS_FORMAT	400	Address structure doesn't meet requirements
MISSING_LOCATION_DATA	400	Location must have either address or coordinates
INVALID_STATUS_TRANSITION	400	Invalid serviceability status change
INVALID_GROUP_REFERENCE	400	Referenced address or location group doesn't exist

Export Error Codes

Code	HTTP Status	Description
INVALID_FORMAT	400	Export format must be 'json' or 'csv'
INVALID_DATE_RANGE	400	modifiedSince must be before modifiedBefore
EXPORT_SIZE_EXCEEDED	400	Export request would generate too large a file
EXPORT_GENERATION_FAILED	500	Failed to generate the export file
EXPORT_NOT_READY	404	Export still processing or doesn't exist

Query Error Codes

Code	HTTP Status	Description
INVALID_STATUS	400	Invalid status value in query parameter
INVALID_LIMIT	400	Limit must be between 1 and 1000
INVALID_OFFSET	400	Offset must be non-negative
INVALID_FILTER	400	Invalid filter parameter or value

Webhook Error Codes

Code	HTTP Status	Description
WEBHOOK_DELIVERY_FAILED	N/A	Failed to deliver event to webhook endpoint
WEBHOOK_TIMEOUT	N/A	Webhook endpoint didn't respond in time
WEBHOOK_INVALID_RESPONSE	N/A	Webhook endpoint returned invalid response

Error Detail Examples

Validation Error with Field Details

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid field value",
    "details": {
      "field": "coordinates.latitude",
      "value": 91.5,
      "constraint": "Must be between -90 and 90"
    }
  }
}

Missing Required Field

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing required field",
    "details": {
      "field": "address.streetNumber",
      "requirement": "required when address is provided"
    }
  }
}

Invalid Enum Value

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid enum value",
    "details": {
      "field": "fiberAccessDetails.serviceability.status",
      "value": "AVAILABLE",
      "allowedValues": ["PLANNED", "CONSTRUCTION", "ACTIVE", "INACTIVE", "CANCELLED", "RETIRED"]
    }
  }
}

Export Size Limit

{
  "error": {
    "code": "EXPORT_SIZE_EXCEEDED",
    "message": "Export would exceed maximum allowed size",
    "details": {
      "estimatedCount": 5000000,
      "maxAllowed": 1000000,
      "suggestion": "Use modifiedSince/modifiedBefore to reduce export size"
    }
  }
}

Resource Not Found

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Location group not found",
    "details": {
      "resourceType": "locationGroup",
      "resourceId": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

Invalid Serviceability Status Transition

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid serviceability status transition",
    "details": {
      "field": "fiberAccessDetails.serviceability.status",
      "currentValue": "CANCELLED",
      "attemptedValue": "ACTIVE",
      "reason": "Cannot transition from terminal state CANCELLED"
    }
  }
}