Erreurs

Les erreurs arrivent toujours au format RFC 9457 application/problem+json :

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://docs.grem.capital/api/errors/business_rule",
  "title": "business_rule",
  "status": 422,
  "detail": "Describe the property: pick a listing or fill in at least a description, city or area",
  "code": "not_enough_input",
  "requestId": "req_..."
}

Une erreur de validation avec des champs :

{
  "title": "validation",
  "status": 400,
  "detail": "\"avatarId\" is required",
  "errors": [{ "field": "avatarId", "message": "\"avatarId\" is required" }],
  "requestId": "req_..."
}

Codes d'erreur

L'URL type mène à l'entrée correspondante de cette liste.

invalid_key

401. La clé est absente, incorrecte, révoquée ou expirée. Vérifiez l'en-tête Authorization et le statut de la clé dans l'espace personnel.

forbidden_scope

403. La clé est valide, mais il lui manque le scope requis. Accordez ce scope ou créez une nouvelle clé (Authentification).

forbidden

403. L'action n'est pas autorisée pour ce compte ou cette ressource : par exemple, l'annonce appartient à un autre compte ou le rôle dans l'agence est insuffisant. La raison figure dans detail.

insufficient_funds

402. Solde du portefeuille insuffisant, quota du forfait épuisé, dette impayée ou limite d'utilisation équitable (fair use) atteinte. code précise lequel : INSUFFICIENT_FUNDS, QUOTA_EXCEEDED, DEBT_OUTSTANDING, FAIR_USE_LIMIT_REACHED, etc. Rechargez le portefeuille, réglez la dette ou changez de forfait.

validation

400. La requête n'a pas passé la validation. Ce qui ne va pas exactement figure dans detail et errors. Corrigez la requête ; la répéter sans modification ne sert à rien.

business_rule

422. La requête est bien formée mais ne peut pas être exécutée : des données manquent, l'annonce n'est pas dans le bon état, le type de bien n'est pas pris en charge, etc. La raison figure dans detail, le code machine dans code.

payload_too_large

413. Le corps de la requête ou un fichier dépasse la limite. Les limites de taille sont indiquées pour chaque outil. Un corps qui n'est pas un JSON valide renvoie 400 validation.

range_not_satisfiable

416. Le Range d'un téléchargement de fichier est en dehors du fichier. Content-Range: bytes */size donne la taille du fichier.

rate_limited

429. Limite de débit dépassée. Attendez le nombre de secondes indiqué par Retry-After, puis réessayez (Limites et facturation). code précise quelle limite : minute_limit (secondes) ou daily_limit (réinitialisée à 00:00 UTC).

not_found

404. Chemin inconnu, ou ressource qui n'existe pas ou ne vous appartient pas. La ressource de quelqu'un d'autre reçoit délibérément la même réponse qu'une ressource inexistante.

idempotency_conflict

409. Une requête avec cette Idempotency-Key est toujours en cours. Attendez qu'elle se termine et réessayez avec la même clé (Idempotence). Après un délai dépassé (502 provider_error), la clé est retenue pendant 15 minutes : vérifiez le résultat avant de répéter - une répétition après ce délai relance le travail payant. L'évaluation express libère la clé après un délai dépassé : répétez-la avec la même clé. Le même 409 est renvoyé lorsque le paiement d'un appel avec cette clé est encore en cours de réservation (code RESERVE_IN_PROGRESS, RESERVE_BUSY) - réessayez plus tard ; RESERVE_REF_TAKEN - la clé est épuisée, envoyez-en une nouvelle.

conflict

409. La ressource est dans un état qui ne permet pas cette action (par exemple, déplacer une annonce entre agences, supprimer une annonce liée à un contrat de commission actif). La raison figure dans detail. Ne répétez pas la requête sans modification.

service_unavailable

503. L'outil est temporairement indisponible. Rien n'a été facturé. Réessayez après la pause indiquée par Retry-After ; GET /tools/status affiche l'état actuel des outils.

provider_error

502. Le service qui effectue le travail a échoué. Problème temporaire : réessayez avec une pause croissante. Si detail indique que l'outil n'a pas répondu à temps, le travail peut encore aboutir et être facturé : vérifiez GET /works avant de le relancer ; répétez l'évaluation express avec la même Idempotency-Key. Les résultats de l'amélioration de photos, des sites et des brouillons ne sont pas conservés dans GET /works : pour eux, attendez la fin de la réservation de 15 minutes et vérifiez le résultat dans l'espace personnel ou parmi vos annonces.

internal_error

500. Erreur interne. Réessayez après une pause ; si l'erreur persiste, contactez le support en indiquant le requestId.

La liste peut s'allonger. Traitez un code inconnu comme une erreur générique de sa classe HTTP (4xx - problème de requête, 5xx - défaillance du service).

Ce qu'il faut relancer

Lorsque vous relancez des requêtes qui créent quelque chose, envoyez toujours la même Idempotency-Key - la nouvelle tentative n'exécutera alors pas le travail deux fois et ne le facturera pas deux fois.

Exceptions

• Les événements Swipe Match (POST /match/leads/{id}/events) non autorisés par l'état actuel du lead renvoient 409 avec title: business_rule et la raison dans code (client_event_rejected, invalid_transition, not_available).
• Les actions sur le pool de leads de l'agence (POST /leads/{id}/claim, POST /leads/{id}/return-to-pool) avec une clé personnelle ou un rôle insuffisant renvoient 403 avec title: forbidden.

Ce qui n'est pas facturé

Une requête refusée (toute réponse 4xx ou 5xx) ne consomme pas d'appel d'API. Le prix de l'outil n'est facturé que pour un travail accepté. L'exception est provider_error après un délai dépassé : le travail peut encore aboutir et être facturé - vérifiez GET /works avant de le relancer (amélioration de photos, site et brouillon : l'espace personnel ou vos annonces).

Voir aussi

• Limites et facturation
• Idempotence
• Authentification