Select matches and deduct credit
POST/search/:searchId/select
A guest has zero account credits: at paymentStage=selection, payment is required and selection is not persisted; at paymentStage=results, selection uses the existing unpaid masked-results path. Guest access requires current session ownership; no guest wallet or paid marker is created.
Selects matches. After selection, matches cannot be changed and only the results endpoint is available.
Whether this call spends a credit depends on the user's paymentStage
(see User.paymentStage on GET /users/me):
selection(or absent): one credit is deducted here. With no credits available the call returns 402 and the selection is rolled back, so it can be retried after buying credits.results: nothing is charged here; the credit is charged by GET /search/{searchId}/results.
Important: This operation can only be performed once per search. If matches are already selected, returns 400 error.
Request
Responses
- 200
- 400
- 401
- 402
- 404
- 409
- 500
- 503
Matches selected (and a credit deducted when paymentStage is selection)
Bad request - matches already selected or invalid selection. Selection cannot be changed after credit is deducted. Also returned when more matches are selected than the search allows: see maxSelectable on GET /search/{searchId}/matches.
Unauthorized
No credits available. Returned only when paymentStage is selection. The selection is rolled back, so the call can be repeated after the user buys credits or a plan.
Not found
App-session guest pending outcome. GeneralError.message is guest_attempt_pending (retryable unfinished attempt) or session_transition_pending (retryable verified-account handoff). An unfinished attempt cannot create a second accepted Search. For authenticated multipart upload, 409 also covers an unfinished account attempt, a same-account/key collision between multipart and direct upload, or replay of a soft-deleted accepted Search. A deleted Search keeps its key consumed; the response discloses no deleted Search data and creates no new reservation. Pending attempts may be retried with the same key.
Response Headers
Seconds to wait before retrying a pending attempt or transition.
Internal server error
Canonical session identity, transaction or admission storage unavailable. Guest requests fail closed instead of receiving a new session or quota. For authenticated multipart upload, infrastructure failure or an uncertain admission outcome also returns 503. Retry with the same account and Idempotency-Key; uncertainty must not create a second accepted Search.