DEV Proposal for better Telemetry error handling

Author: nheilbuth

agency/README.md

@@ -224,16 +224,9 @@ Body Params:
 | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------- |
 | `success`  | Integer                        | Number of successfully written telemetry data points.                                                   |
 | `total`    | Integer                        | Total number of provided points.                                                                       |
-| `failures` | [Telemetry](#telemetry-data)[] | Array of failed telemetry for zero or more vehicles (empty if all successful).                          |
+| `failures` | [Telemetry Error](#telemetry-error)[] | Array of errors including the failed telemetry data and error details (empty if all successful).                          |
 
-400 Failure Response:
-
-| `error`         | `error_description`                  | `error_details`[]                 |
-| --------------- | ------------------------------------ | --------------------------------- |
-| `bad_param`     | A validation error occurred.         | Array of parameters with errors   |
-| `invalid_data`  | None of the provided data was valid. |                                   |
-| `missing_param` | A required parameter is missing.     | Array of missing parameters       |
-| `unregistered`  | Some of the devices are unregistered | Array of unregistered `device_id` |
+Alway returns 200. Any failed data is detailed in the `failures` array of the response.
 
 [Top][toc]
 
@@ -259,6 +252,24 @@ A standard point of vehicle telemetry. References to latitude and longitude impl
 
 [Top][toc]
 
+## Telemetry Error
+Error response for indicating failed telemetry data for the [Telemetry](#vehicle---telemetry) endpoint
+
+| Field          | Type                           | Field Description
+| -------------- | ------------------------------ | --------------------------------- |
+| `telemetry`    | [Telemetry](#telemetry-data)   | The failed telemetry data         |
+| `error`        | [Error Message][error-message] | Error message detailing the error |
+
+ Errors:
+
+| `error`         | `error_description`                  | `error_details`[]                 |
+| --------------- | ------------------------------------ | --------------------------------- |
+| `bad_param`     | A validation error occurred.         | Array of parameters with errors   |
+| `missing_param` | A required parameter is missing.     | Array of missing parameters       |
+| `unregistered`  | Vehicle is not registered            |                                   |
+
+[Top][toc]
+
 ## Stops
 
 The `/stops` endpoint allows an agency to register city-managed Stops, or a provider to register self-managed Stops.
@@ -342,3 +353,4 @@ If `stop_id` is specified, `GET` will return an array with a single stop record,
 [vehicle-states]: /general-information.md#vehicle-states
 [vehicle-events]: /general-information.md#vehicle-state-events
 [versioning]: /general-information.md#versioning
+[error-message]: /general-information.md#error-messages