Errors and troubleshooting | Data for Tennis API Documentation

Current measured availability and source checks: System status. Read the monitoring definitions 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.