Skip to content

Errors#

The Partner API uses standard HTTP status codes. Error responses follow FastAPI's convention:

{ "detail": "Referral link has expired" }

Status codes#

Code Meaning Example messages
200 Success (GET / list / validate). —
400 Request body failed validation. Field-level constraint errors.
401 Missing or invalid authentication. X-API-Key header required, Invalid API key
404 Resource not found or not owned by caller. Invalid or expired referral code, Referral link not found, API key not found
409 Conflict during trial claim. Username already taken, Email already registered, A trial has already been claimed with this email
410 Referral link no longer usable. Referral link has expired, Referral link has reached its usage limit
429 Rate limit exceeded (trial claim). Returned after 5 claims/hour from one IP.
500 Unexpected server error. —

Notes#

  • GET /partner/referral/{code}/validate never returns 404/410 for a bad code — it returns 200 with { "valid": false, "trial_duration_days": 0 } instead. The 404/410 messages above apply to POST /partner/trial/claim, which validates the code strictly.
  • 404 on management endpoints (DELETE referral links / API keys) covers both "does not exist" and "not owned by you" — the API does not distinguish the two.