Error Responses

All Open Access Forum APIs use a consistent error response format compatible with common HTTP client libraries.

Error Response Format

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}  // optional
  }
}

Standard HTTP Status Codes

Success Codes

• 200 OK - Request succeeded
• 201 Created - Resource created successfully
• 202 Accepted - Request accepted for asynchronous processing
• 204 No Content - Request succeeded with no response body

Client Error Codes

• 400 Bad Request - Invalid request syntax or parameters
• 401 Unauthorized - Missing or invalid authentication
• 403 Forbidden - Valid authentication but insufficient permissions
• 404 Not Found - Resource does not exist
• 409 Conflict - Request conflicts with current state
• 422 Unprocessable Entity - Request syntax valid but semantically incorrect
• 429 Too Many Requests - Request rate exceeded

Server Error Codes

• 500 Internal Server Error - Unexpected server error
• 502 Bad Gateway - Invalid response from upstream server
• 503 Service Unavailable - Service temporarily unavailable
• 504 Gateway Timeout - Upstream server timeout

Error Code Standards

Error codes should be:

• UPPER_SNAKE_CASE format
• Descriptive and specific
• Consistent across the API

Common Error Codes

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request body is not valid JSON"
  }
}

{
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "message": "The provided authentication token is invalid or expired"
  }
}

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Location with ID 123e4567-e89b-12d3-a456-426614174000 not found"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "field": "coordinates.latitude",
      "constraint": "Must be between -90 and 90"
    }
  }
}