Merge pull request #3929 from segmentio/3373-content-add-additional-causes-for-rejected-events

Added more clarity to HTTP API errors section

Author: forstisabella

src/connections/sources/catalog/libraries/server/http-api/index.md

@@ -24,9 +24,16 @@ To send data to Segment's HTTP API, a content-type header must be set to `'appli
 
 ## Errors
 
-Segment returns a `200` response for all API requests so debugging should be done in the Segment Debugger. The only exception is if the request is too large / JSON is invalid it will respond with a `400`.
+Segment returns a `200` response for all API requests except errors caused by large payloads and JSON errors (which return `400` responses.) To debug events that return `200` responses but aren't accepted by Segment, use the Segment Debugger.
 
-Segment welcomes feedback on API responses and error messages. [Reach out to support](https://segment.com/help/contact/) with any requests or suggestions you may have.
+Common reasons events are not accepted by Segment include: 
+  - **Payload is too large:** The HTTP API can handle API requests that are 32KB or smaller. The batch API endpoint accepts a maximum of 500KB per request, with a limit of 32KB per event in the batch. If these limits are exceeded, Segment returns a 400 Bad Request error. 
+  - **Identifier is not present**: The HTTP API requires that each payload has a userId and/or anonymousId.
+  - **Track event is missing name**: All `track` events sent to Segment must have an `event` field. 
+  - **Deduplication**: Segment deduplicates events using the `messageId` field, which is automatically added to all payloads coming into Segment. If you're setting up the HTTP API yourself, ensure all events have unique messageId values.
+  - **Invalid JSON**: If you send an event with invalid JSON, Segment returns a 400 Bad Request error.
+
+Segment welcomes feedback on API responses and error messages. [Reach out to support](https://segment.com/help/contact/){:target="_blank"} with any requests or suggestions you may have.
 
 ## Rate Limits