Handle API errors

Every third-party API error carries an HTTP status, a string code, and a message. Match on the code, and retry only what's safe to retry.

This page covers the endpoints under /api/thirdparty: the access token, communities, groups, members, moderators, and video posts. Each endpoint's reference lists the errors it returns. This page explains the shape they share and what to do about each one.

The error response

An error has an HTTP status in the 4xx range and a JSON body with three fields.

{
  "code": "5218",
  "message": "The community you are looking for is no longer available.",
  "data": {}
}

A successful call uses the same three fields with code set to the number 200, so a client can read every response the same way. On errors the code is a string; on success it's a number.

Validation errors

Each endpoint checks the body against its schema before doing anything. How it reports a failure differs by endpoint.

For the three endpoints that return an empty body, compare your request with the endpoint's Parameters table. The usual causes are a value of the wrong type, such as a number where a string is expected, a value outside its allowed set, and a missing required field.

Authentication errors

Every endpoint except the token endpoint reads the bearer token from the Authorization header before anything else. Three errors come from that check.

Error codes

Codes are shared across endpoints. This table lists every code the third-party endpoints return, grouped by HTTP status.

What to retry

Treat a 422 or a 1099 on a write as indeterminate: the change may have been saved. Retrying is still safe on these endpoints, because the duplicate checks turn a second save into a 409.

• A repeated Post a video to a group with the same video_name or message_id returns 409 with code 5057. That tells you the first call succeeded.
• A repeated Create a community with the same handle returns 409 with code 5216.
• A repeated Update a group and its members is harmless. Fields already at the new value come back with false in their _updated flag, and members already in the group aren't added twice.

Pass your own message_id on Post a video, and keep the same handle on Create a community. A repeated call is then rejected as a duplicate instead of creating a second record. The third-party endpoints have no rate limit, so a retry only needs to wait for the server-side failure to clear; a second or two is enough.

When you contact the Genuin team about an error, include the HTTP status, the code, the message, the endpoint, and the request time in UTC. A 1099 can only be traced from the server side, and the timestamp is how it's found.

Limitations

• Codes aren't unique across the platform: 5243 also names an unrelated server error elsewhere. On the third-party endpoints it always means the brand mismatch above.
• Three endpoints report no validation detail: Create a group, Post a video, and Update a group return 400 with an empty body.
• Messages are English only, and some carry the literal XXXX- prefix. Map codes to your own text rather than showing messages to members.

See also

• Generate an access token
• Create a community
• Create a group in a community
• Post a video to a group
• Update a group and its members
• Add moderators to a community
• Add members to a community