Erreurs

Une seule enveloppe, un mot-clé stable, une phrase lisible, un identifiant de requête.

HTTP/1.1 422 Unprocessable Entity
X-Request-Id: 2b7a…

{
  "error": {
    "type": "validation_error",
    "message": "The request body is not valid",
    "request_id": "2b7a…",
    "fields": [{"field": "to.number", "message": "must be an E.164 phone number, like +15145550100"}]
  }
}

Testez error.type, jamais le texte de message : la phrase peut changer, le mot-clé non. request_id est aussi l'en-tête X-Request-Id, présent sur toutes les réponses, réussies ou non.

type	HTTP	Sens
`invalid_request`	400	Quelque chose cloche dans la requête : paramètre invalide, jeton de synchronisation expiré, curseur invalide
`unauthorized`	401	Le jeton est absent, inconnu, expiré ou révoqué
`forbidden`	403	Le jeton est valide mais ne peut pas faire ceci (jeton client_credentials sur une route « moi », app suspendue)
`insufficient_scope`	403	Le jeton n'a pas la permission qu'exige cette route ; WWW-Authenticate la nomme
`not_found`	404	Objet inexistant, ou invisible pour ce jeton
`conflict`	409	Le changement entre en conflit avec l'état actuel (numéro déjà attribué, doublon)
`validation_error`	422	Le corps n'est pas valide ; fields détaille chaque problème
`rate_limited`	429	Au-delà du palier ; attendez Retry-After secondes
`server_error`	500	De notre faute. Citez request_id en nous écrivant

Seule exception : POST /oauth/token répond dans la forme de la RFC 6749 ({"error": "invalid_grant", "error_description": "…"}, ou invalid_client, invalid_scope, unsupported_grant_type), parce que les bibliothèques OAuth s'y attendent.