Errors

The API returns error responses in a consistent format:

{
  "statusCode": 400,
  "message": "Description of the error",
  "timestamp": "2026-04-04T12:00:00.000Z"
}

Common Error Codes

Code	Meaning	Example
400	Invalid parameters	`"limit must not be greater than 100"`
400	Batch size exceeded	`"Batch size exceeds limit of 10 for FREE plan"`
401	Missing or invalid API key	`"Missing X-API-Key header"`
404	Card not found	`"Card with externalId 999 not found in riftbound"`
429	Daily rate limit exceeded	`"Daily rate limit of 100 requests exceeded for FREE plan"`
500	Internal server error	Unexpected error — please report if persistent

Request parameters are strictly validated. Unknown fields are rejected:

{
  "statusCode": 400,
  "message": ["game must be a string", "name should not be empty"],
  "timestamp": "2026-04-04T12:00:00.000Z"
}

When you send more card IDs than your plan allows:

{
  "statusCode": 400,
  "message": "Batch size exceeds limit of 10 for FREE plan",
  "timestamp": "2026-04-04T12:00:00.000Z"
}