Salta al contingut
CA ES
Sol·licita una demo

Desenvolupadors

Errors

Format d'error, tots els codis estables, el seu estat HTTP i què fer en cada cas.

Tots els errors de l'API tenen el mateix format JSON i un codi estable que pots fer servir al teu codi. El text de message és en anglès i pot canviar, i els missatges de details en errors de validació surten en l'idioma per defecte de la plataforma (avui català), no en el del club ni en anglès; programa contra code i contra l'estat HTTP, no contra el missatge.

Format

{
  "error": {
    "code": "validation_failed",
    "message": "The given data was invalid.",
    "details": {
      "ends_at": ["L’hora de fi ha de ser posterior a l’hora d’inici."]
    }
  }
}
  • code: identificador estable en snake_case.
  • message: descripció llegible en anglès. No la mostris tal qual als teus usuaris.
  • details: sempre present; és {} quan no hi ha res a afegir. A validation_failed, conté els errors per camp; els textos són en l'idioma per defecte de la plataforma (a l'exemple, català), així que no programis contra ells: fes servir el nom del camp.

Codis

Codi HTTP Quan passa Què fer
unauthenticated 401 Falta el token, no existeix o no és vàlid. La resposta inclou WWW-Authenticate: Bearer. Revisa la capçalera Authorization: Bearer ….
token_expired 401 La credencial ha caducat. Crea una credencial nova al tauler.
token_revoked 401 La credencial ha estat revocada. Crea una credencial nova al tauler.
feature_disabled 403 El club no té activada la funció integrations. Demana-la a l'equip de Pranarp Club.
insufficient_ability 403 La credencial no té el permís necessari. details.required indica quin. Crea una credencial amb aquest permís.
space_not_allowed 403 La credencial no pot fer servir aquest espai. details.space_id indica quin. Amplia els espais de la credencial o fes-ne servir un altre.
not_owner 403 Intentes modificar o cancel·lar una reserva que no ha creat aquesta credencial, sense el permís bookings:write_all. Fes servir la credencial que la va crear o concedeix bookings:write_all.
booking_not_modifiable 403 La reserva prové d'una activitat del club i no es pot modificar per l'API. No reintentis; gestiona-la des del tauler.
not_found 404 El recurs no existeix, és inactiu/eliminat o és d'un altre club. Revisa l'identificador.
slot_unavailable 409 La franja ja no està disponible (reserva, bloqueig o aforament). Consulta la disponibilitat i tria'n una altra.
idempotency_conflict 409 Mateixa Idempotency-Key amb un altre cos, o la petició original encara és en curs. Vegeu idempotència.
validation_failed 422 Dades invàlides. details llista els errors per camp. Corregeix els camps indicats.
player_not_found 422 Alguna referència external_ref de players no està sincronitzada. details.players llista les que falten. Sincronitza-les abans amb PUT /players/{external_ref}.
rate_limited 429 Has superat les 120 peticions per minut. Inclou Retry-After. Espera i reintenta; vegeu límits de ritme.

Altres errors genèrics

No formen part dels codis anteriors, però tenen el mateix format:

Codi HTTP Significat
forbidden 403 Fallada d'autorització genèrica fora dels casos anteriors.
method_not_allowed 405 El mètode no existeix per a aquella ruta; la capçalera Allow llista els admesos.
http_error altres 4xx Un altre error de client sense codi específic.
server_error 500 Error intern. Reintenta amb backoff; si persisteix, contacta amb nosaltres.

Gestió recomanada

  • 4xx (excepte 409 per conflicte temporal i 429): l'error és teu; reintentar sense canviar res donarà el mateix resultat.
  • 429 i 5xx: reintenta amb espera exponencial (i Retry-After quan existeixi), sempre amb la mateixa Idempotency-Key a les creacions.
  • 409 slot_unavailable: no és una fallada tècnica, és un conflicte de negoci normal. Torna a consultar la disponibilitat.

Exemple de 409 en crear una reserva:

curl -s -i -X POST "$PRANARP_URL/api/v1/bookings" \
  -H "Authorization: Bearer $PCK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"space_id":7,"starts_at":"2026-10-22T18:00:00+02:00","ends_at":"2026-10-22T19:00:00+02:00","holder":{"name":"Laura Pons"}}'

{
  "error": {
    "code": "slot_unavailable",
    "message": "The requested time slot is not available.",
    "details": {}
  }
}