Errors - Retain

Troubleshoot problems with this comprehensive breakdown of all error codes.

Error schema

We use standard HTTP response codes for success and failure notifications. All errors return a consistent format:

{
  "message": "Human-readable error description",
  "statusCode": 400,
  "name": "validation_error"
}

Use the name field for programmatic error handling in your SDK or application.

Error codes

`validation_error`

Status: 400
Message: Varies. Describes which field failed validation and why.
Suggested action: Check the message field for details. Common causes: missing required fields (userId, email for identify; userId, event for track), invalid email format, invalid URL in avatar, or event name containing spaces.

`invalid_write_key`

Status: 401
Message: Missing or invalid Project Token.
Suggested action: Include the Authorization: Basic rk-xxxxxxxxx header with a valid Project Token. Ensure the token starts with rk- and has not been revoked.

`not_found`

Status: 404
Message: User not found, please identify the user first using the /identify endpoint.
Suggested action: Call POST /identify before POST /track. Events can only be recorded for users that have been identified.

`rate_limit_exceeded`

Status: 429
Message: Too many requests. Please limit the number of requests per second.
Suggested action: Reduce the rate of API requests. Consider batching events or introducing a queue. If you need higher limits, contact support.

`application_error`

Status: 500
Message: An unexpected error occurred, please try again later.
Suggested action: Retry the request. If the error persists, check our status page or contact support.

Identify a user