> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.datafortennis.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.datafortennis.com/_mcp/server.

# Errors and troubleshooting

Current measured availability and source checks: [System status](https://status.datafortennis.com). Read the [monitoring definitions](/start-here/service-status) before interpreting uptime or an empty live response.


Errors use the same envelope: `data`, `meta` and `page` are null, and `error`
contains `code`, `message` and `request_id`. Preserve the request ID when reporting
a failure. Do not include credentials, local paths or provider payloads in a report.

| HTTP status | Common meaning | Client action |
| --- | --- | --- |
| 400 | Invalid input, incompatible cursor or filter | Correct the request; do not retry unchanged |
| 401 | Missing or invalid authentication | Correct or rotate credentials |
| 403 | Current capability or release access denied | Check current entitlement |
| 404 | Unknown entity or foreign owner-bound artifact | Verify the own ID and release |
| 409 | Key/request conflict or ambiguous identity | Preserve canonical request or resolve candidates |
| 410 | Replay, change retention or artifact expired | Resync/recreate under the applicable contract |
| 413 | Request/body exceeds its bound | Reduce the request |
| 429 | Rate or concurrency budget exhausted | Follow retry guidance with bounded backoff |
| 503 | Dependency, request/query deadline or admission failure | Reduce scope or retry cautiously with stable logical identity |

A non-JSON `403` can come from the edge before the API, so it does not establish
that an entitlement is missing. In the current deployment, the default
`Python-urllib` user agent received an edge `403`, while an authenticated Python
request identifying its own application as `User-Agent: YourTennisApp/1.0`
received `200`. Use your actual application name and version; do not impersonate
a browser. Authentication is still required: the same application header without
a Bearer credential received `401`. Keep the response content type and request ID
when investigating a failure, and never include the key or ticket.

Exact endpoint responses are listed in the API reference. A known match with no
accepted points or statistics is not the same as an unknown match. Inspect the
successful empty response's availability and capability metadata.

For subscription access,403 can also mean no current funded period or an expired
control lease.429 includes the customer's shared monthly request allowance.
When a replay crosses the subscription-period boundary,409 requires a new
idempotency key for a new operation. These are data API responses; payment
callbacks and browser checkout responses have their own private contract.

`/health/live` reports process liveness and `/health/ready` reports readiness without
credentials or SQL details. A health response alone does not prove a release has
complete PBP, that a marketplace is integrated, or that a remote gateway is healthy.

In the private LAN profile, the gateway requires its trusted client certificate
and the documented Bearer header before forwarding health routes. TLS rejection
can happen before any HTTP response. Keep certificate trust, hostname validation
and API key authentication as separate checks. A readiness503 after cancellation
can be temporary; poll with a bounded recovery window rather than restarting a
live process for every failed readiness probe.

Cursor signatures bind the principal, route, release and filters. Synchronize
host clocks; cursor issuance is bounded to24hours and decoding tolerates a small
backward clock correction without extending the cursor's absolute expiry. An
expired cursor still returns410 and requires the documented resync workflow.