Returning.AIDevelopers
v1

API reference / Gamification / Match Predictions

.md

Void match prediction

Cancel a published match prediction and refund every trader's entry cost, without paying any rewards.

Last updated 26 Sep 2026API v1

Method
POST
Path
https://api.returning.ai/v1/match-predictions/{matchPredictionId}/void
Permission
matchPredictions
Retries
Idempotency-Key required; same key and body replays

When to use this

  • The fixture was cancelled, abandoned or declared invalid.
  • A published match was set up wrongly and shouldn't pay out.
  • An earlier void failed and you need to run it again.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
matchPredictionsShown in the dashboard as “Match Prediction”

Use a Community API key with matchPredictions, shown in the dashboard as Match Prediction, and keep it on your server. The key decides the community: you only see and change match predictions in that community, and an ID from another community returns 404, the same as an unknown ID. Personal API keys are rejected with 403.

Behaviour#

api.returning.ai doesn't serve this route yet: requests return an empty 404. Ask Returning.AI before you build on it.

A void runs in the background: a 202 means it has started. Traders can't submit predictions once it starts, and the match shows void_in_progress. Poll Get settlement results until it returns 200 MATCH_PREDICTION_VOID_COMPLETED.

You can void a published match at any time, before or after kickoff, unless it is already settled or voided or another settlement or void is running. A match whose void failed can be voided again.

Every trader who paid an entry cost gets those coins back, and nobody gets rewards. The match becomes voided once every prediction has been handled.

Request#

Path parameters#

matchPredictionId#stringREQUIRED
The match prediction ID from Create match prediction or List match predictions.

Rulemp_ and 24 hex characters

Eg"mp_66f000000000000000000801"

Headers#

Authorization#stringREQUIRED
Community API key with matchPredictions.

RuleBearer <API_KEY>

Idempotency-Key#stringREQUIRED
A unique key you create for this void, such as a UUID. Reuse it only to retry the same body.

Rule1-255 characters

Eg"3f9c2a7e-1b4d-4e8a-9c61-2d5f7a8b9e10"

Content-Type#stringREQUIRED
Request body format. Anything else returns 415.

Ruleapplication/json

X-Request-Id#stringOPTIONAL
Your own ID for this request, returned in meta.requestId. Without it, a req_... ID is generated.

Body#

reason#stringREQUIRED
Why you are voiding the match. Recorded with the void.

Rulefixture_cancelled, fixture_abandoned, fixture_invalid or operator_error

Eg"fixture_cancelled"

curl --request POST \
  --url https://api.returning.ai/v1/match-predictions/mp_66f000000000000000000801/void \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Idempotency-Key: 3f9c2a7e-1b4d-4e8a-9c61-2d5f7a8b9e10' \
  --header 'Content-Type: application/json' \
  --data '{
    "reason": "fixture_cancelled"
  }'

Response#

A 202 returns the void's operationId and the resultsUrl to poll.

meta#objectALWAYS
Result details.
status#stringALWAYS
Result of the request.

Rulesuccess

statusCode#integerALWAYS
The HTTP status, repeated.
code#stringALWAYS
Machine-readable result code.

RuleMATCH_PREDICTION_VOID_ACCEPTED

requestId#stringALWAYS
Your X-Request-Id if you sent one, otherwise a generated req_... ID. Quote it when you contact support.
message#stringALWAYS
Human-readable summary. Do not branch on it.
data#objectALWAYS
The void that was started.
operationId#stringALWAYS
The void ID.

Rulempv_ and 32 hex characters

type#stringALWAYS
Always void.
status#stringALWAYS
void_in_progress when it starts. A replay shows the status the void had then.
submittedAt#stringALWAYS
When the void was accepted.
resultsUrl#stringALWAYS
Where to poll for the outcome, without the host.
{
  "meta": {
    "status": "success",
    "statusCode": 202,
    "code": "MATCH_PREDICTION_VOID_ACCEPTED",
    "requestId": "req_66f00000000000000000000000000811"
  },
  "message": "Match prediction void accepted.",
  "data": {
    "operationId": "mpv_66f00000000000000000000000000804",
    "type": "void",
    "status": "void_in_progress",
    "submittedAt": "2026-10-10T17:00:00.000Z",
    "resultsUrl": "/v1/match-predictions/mp_66f000000000000000000801/results"
  }
}

Errors#

Every error carries its code in meta.code and the request's ID in meta.requestId. Validation errors list each problem in details, with a field, code and message. The API key checks (401, 403, 404 COMMUNITY_NOT_FOUND and 500 AUTHENTICATION_FAILED) return detail and solution instead. A 404 with an empty body means the route isn't available on api.returning.ai yet. A 400 or 409 changes nothing.

Fix the request10

404Fix the request
The body is empty: api.returning.ai doesn't serve this route yet. Ask Returning.AI before you build on it.
400MATCH_PREDICTION_VALIDATION_FAILEDFix the request
reason is missing or not one of the four values, or the body has another field. details names it. Nothing changed.
400READ_ONLY_FIELDFix the request
The request has a field the server sets, such as status or settlement. details names it. Remove it.
400INVALID_JSONFix the request
The body is not valid JSON. Fix the syntax and send it again.
400IDEMPOTENCY_KEY_REQUIREDFix the request
Send an Idempotency-Key header with a unique value.
400IDEMPOTENCY_KEY_INVALIDFix the request
The Idempotency-Key is longer than 255 characters. Use a shorter key, such as a UUID.
415UNSUPPORTED_MEDIA_TYPEFix the request
Send the body as JSON with Content-Type: application/json.
401AUTHENTICATION_REQUIREDFix the request
The key is missing, invalid or expired. Send Authorization: Bearer <API_KEY> with a current Community API key.
403API_KEY_PERMISSION_DENIEDFix the request
The key lacks matchPredictions, or it is a personal key. Use a Community API key and add Match Prediction in Settings > Integration > API Keys.
409IDEMPOTENCY_KEY_CONFLICTFix the request
This Idempotency-Key was already used with a different body. Use a new key for a new body.

Fix the data06

404MATCH_PREDICTION_NOT_FOUNDFix the data
No match prediction in your community has this ID. Check it is the full mp_... ID from Create match prediction or List match predictions.
404COMMUNITY_NOT_FOUNDFix the data
The community this key belongs to no longer exists. Contact Returning.AI support.
409INVALID_LIFECYCLE_TRANSITIONFix the data
The match is a draft, which has nothing to refund and can't be voided. It stays a draft.
409MATCH_ALREADY_SETTLEDFix the data
The match is already settled, and a settlement can't be reversed. Nothing changed.
409MATCH_ALREADY_VOIDEDFix the data
The match is already voided. Nothing more to do.
409OPERATION_IN_PROGRESSFix the data
A settlement or another void is running on this match. Check the outcome with Get settlement results.

Retry with backoff05

429RATE_LIMITEDRetry with backoff
Your community is over its rate limit. Wait for the seconds in Retry-After, then retry.
500INTERNAL_ERRORRetry with backoff
The outcome is unclear. Check Get settlement results before you send the void again with a new key.
500AUTHENTICATION_FAILEDRetry with backoff
The key could not be checked. Retry with backoff; nothing changed.
503VOID_QUEUE_UNAVAILABLERetry with backoff
The void couldn't be started, and nothing changed. Retry later with a new Idempotency-Key: the same key returns this 503 again.
503MATCH_PREDICTION_FROZENRetry with backoff
Returning.AI has paused match prediction requests. Nothing changed. Retry later with backoff.
{
  "meta": {
    "status": "error",
    "statusCode": 404,
    "code": "MATCH_PREDICTION_NOT_FOUND",
    "requestId": "req_66f00000000000000000000000000811"
  },
  "message": "Match prediction not found."
}

Next step#

Get settlement resultsGET/v1/match-predictions/{matchPredictionId}/resultsPoll until the void finishes, then check each trader's refund.