Error Codes Reference

When a request fails, the API returns a non-empty error object in the response envelope:

{
  "metadata": { "timestamp": "2026-02-27T12:00:00.000000+00:00" },
  "pagination": { "page": 1, "items": 0, "total_pages": 1, "total_items": 0, "next_page": null },
  "error": { "code": "InvalidPageNum", "message": "page_num must be greater than 0" },
  "data": null
}

error is an empty object ({}) on success. On failure it contains two fields:

Field	Type	Description
code	string	Machine-readable error identifier — use this for programmatic handling
message	string	Human-readable description of what went wrong

---

v2 Error Codes

Pagination errors

Code	HTTP	Fires when	Remediation
InvalidPageNum	400	page_num ≤ 0	page_num must be greater than 0. Start at page_num=1.
InvalidPageSize	400	page_size outside the range 1–100	Use a page_size between 1 and 100.
DeepPageWithoutFilter	400	page_num > 100 with no narrowing filter and no cursor — applies to /fights/ (requires date_from/date_to, date, event_id, fighter_id, or division_id) and /fights/schedule/ (requires date, event_id, fighter_id, or division_id)	Add at least one of the accepted narrowing filters, or use cursor-based pagination (cursor param from pagination.next_page).
PageLimitExceeded	400	(page_num - 1) * page_size >= 10000, regardless of filters, checked after DeepPageWithoutFilter	Your offset has reached 10,000 or more documents. Switch to cursor-based pagination — follow the pagination.next_page URL instead of incrementing page_num.
InvalidCursor	400	Malformed or invalid cursor token	Do not manually construct or modify cursor tokens. Use the cursor value from pagination.next_page verbatim.

Input validation errors

Code	HTTP	Fires when	Remediation
InvalidDate	400	date parameter is not in YYYY-MM-DD format	Use ISO date format, e.g. 2026-03-15.
InvalidDateRange	400	date_from/date_to are individually invalid, or date_from > date_to	Ensure both dates are valid YYYY-MM-DD strings and that date_from is on or before date_to.
InvalidDays	400	days ≤ 0 on /fights/schedule/	days must be a positive integer.
InvalidPastHours	400	past_hours is negative on /fights/schedule/	past_hours must be 0 or a positive integer.
InvalidId	400	A division_id, event_id, fighter_id, or organization_id is not a valid MongoDB ObjectId	Check the ID format — valid IDs are 24-character hex strings. IDs are returned in API responses and should not be hand-constructed.

Access / subscription errors

Code	HTTP	Fires when	Remediation
DateOutOfRange	403	The requested date falls outside your subscription tier’s historical window	Upgrade your plan on RapidAPI to access a wider date range.
UpgradeRequired	403	The fight exists in the database but is not accessible on your current tier	Upgrade your plan to access this fight.

Not found

Code	HTTP	Fires when	Remediation
NoResults	404	No document matches the given ID	Verify the ID is correct. IDs are stable — if the document existed, the same ID will return it again.

Server errors

Code	HTTP	Fires when	Remediation
SerializationError	500	Internal response validation failure (ResponseValidationError)	This is a server-side error, not caused by your request. Do not retry blindly — if it persists across multiple requests for the same resource, report it via the RapidAPI support channel. A SerializationError 500 is distinct from a transient network 5xx and is worth logging separately.

---

v1 Error Codes (deprecated — sunsets 2026-11-01)

v1 deprecation

v1 reaches end-of-life on 2026-11-01. Migrate to v2 before that date.

Most v1 router-generated errors use a different envelope from v2. Instead of the v2 response structure, v1 router errors wrap the detail in FastAPI’s bare format:

{
  "detail": {
    "code": "InvalidPageNum",
    "message": "page_num must be greater than 0"
  }
}

Exception: SerializationError is raised by a globally registered handler (response_validation_handler in app/main.py) that returns the full API envelope — { "error": { "code": "SerializationError", ... } } — in both v1 and v2. It does not use the bare detail wrapper.

v1 also has one error code not present in v2:

Code	HTTP	Fires when	Remediation
UnfilteredPageSizeTooLarge	400	Unfiltered v1 request with page_size > 20	Add at least one narrowing filter (e.g. fighter_id, event_id, date) or reduce page_size to 20 or below. For new integrations, migrate to v2, which removes this restriction.