​

Envelope de erro

{
  "ok": false,
  "error": {
    "code": "INVALID_JSON_BODY",
    "message": "Invalid JSON body",
    "detailed": {
      "message": "Expected a valid E.164 phone number in \"to\""
    }
  }
}

​

Comportamento real de status code

​

Headers de rate limit

• X-RateLimit-Global
• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Retry-After
• X-RateLimit-Retry-Policy

• X-RateLimit-Retry-After vem em milissegundos.
• O body de erro tambem inclui error.detailed.retryAfterInSeconds.
• O backend nao adiciona hoje o header padrao Retry-After.

​

Guia de retry

• 429
• 5xx transientes

• 400 INVALID_JSON_BODY
• 401 INVALID_OR_MISSING_API_KEY
• 403 MISSING_PERMISSION
• 403 PROJECT_SUBSCRIPTION_REQUIRED
• 403 PROJECT_BILLING_PAYMENT_REQUIRED
• 403 API_KEY_MODE_MISMATCH

​

Idempotencia

• Reusar a mesma key para a mesma operacao reaproveita o resultado salvo.
• Mismatch de payload de OTP retorna 400 INVALID_JSON_BODY.
• A API publica nao expoe hoje um erro dedicado de conflito de idempotencia.

​

Error codes comuns na pratica

• INVALID_CONTENT_TYPE
• INVALID_JSON_BODY
• INVALID_OR_MISSING_API_KEY
• MISSING_PERMISSION
• BRAZILIAN_PHONE_NUMBER_REQUIRED
• PROJECT_SUBSCRIPTION_REQUIRED
• PROJECT_BILLING_PAYMENT_REQUIRED
• PROJECT_MESSAGE_QUOTA_REACHED
• PROJECT_WEBHOOK_LIMIT_REACHED
• WEBHOOK_ENDPOINT_ALREADY_EXISTS
• TEMPLATE_NAME_ALREADY_EXISTS
• UNKNOWN_MESSAGE
• UNKNOWN_TEMPLATE
• UNKNOWN_WEBHOOK
• UNKNOWN_LOG
• RATE_LIMITED
• MESSAGE_PROVIDER_ERROR
• OTP_PROVIDER_ERROR
• API_KEY_MODE_MISMATCH
• INTERNAL_SERVER_ERROR