http_api_errors.md

HTTP API Errors

Proposed Error Structures

Simple Example

{
  "type": "supported_error_type",
  "message": "a message describing the error in general"
}

Examples

{
  "type": "format_validation_error",
  "message": "invalid uuid: abc123"
}

{
  "type": "data_validation_error",
  "message":"region must be one of: us-west,us-east"
}

---

More Complex Example

{
  "code": "<service_name>.<operation_name>.<generic_error_type>",
  "context": [
    {
      "code": "<service_name>.<operation_name>.<specific_error_type>",
      "field": "field_name1",
      "violated_constraints": {
        "constraint_name1": "field_name1_constraint_value1",
        "constraint_name2": "field_name1_constraint_value2"
      }
    },
    {
      "code": "<service_name>.<operation_name>.<specific_error_type>",
      "field": "field_name2",
      "violated_constraints": {
        "constraint_name1": "field_name2_constraint_value1",
        "constraint_name2": "field_name2_constraint_value2"
      }
    }
  ]
}

Examples

{
  "code": "session_manager.get_sessions_status.format_validation_error",
  "context": [
    {
      "code": "session_manager.get_sessions_status.invalid_value",
      "field": "session_ids"
    }
  ]
}

{
  "code": "session_manager.create_session.data_validation_error",
  "context": [
    {
      "code": "session_manager.create_session.invalid_value",
      "field": "regions",
      "violated_constraints": {
        "enum": ["us-east", "us-west"]
      }
    },
    {
      "code": "session_manager.create_session.invalid_value",
      "field": "whitelist",
      "violated_constraints": {
        "max": 500
      }
    }
  ]
}

Error Types

format_validation_error

Returned when the format of the request is wrong / malformed

Typically a 400

data_validation_error

Returned when the format of the request is correct, but its data comes in violation with the current request

Typically a 400

resource_not_found_error

Returned when a resource on the server is not found. Can be used for both: not found routes and not found resources Typically a 404

forbidden_error

Returned when the user tries to access a resource that does not belong to them Typically a 403

auth_error

Returned when the caller is either not authenticated or when it has invalid / expired / forged access token Typically a 401

service_error

Returned when the server cannot handle the request for whatever reason or failure, a very generic server error Typically a 500

service_unavailable_error

Returned when the server attempts to make an external call / database call / any kind of transient API call and the underlying service is not available at that time

Typically a 503

Other error types, are either too specific or ought to be documented and implemented in some shared library.