Mga Code ng Error - Dokumentasyon ng API

Format ng Error Response

Lahat ng error response ay gumagamit ng pare-parehong format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Nababasang mensahe ng error",
    "details": "Karagdagang konteksto (opsyonal)"
  }
}

💡 Gamitin ang error.code bilang stable condition (ang error message ay maaaring magbago)

Mga HTTP Status Code

200 OK

Matagumpay ang kahilingan

200

201 Created

Matagumpay na nalikha ang resource

201

400 Bad Request

Mali ang mga parameter ng kahilingan

400

{
  "code": "INVALID_REQUEST",
  "message": "Mali ang format ng kahilingan"
}

401 Unauthorized

Hindi naka-authenticate o mali ang API key

401

{
  "code": "UNAUTHORIZED",
  "message": "Mali o expired na API key"
}

403 Forbidden

Hindi sapat ang balanse ng account o walang pahintulot

403

{
  "code": "INSUFFICIENT_BALANCE",
  "message": "Hindi sapat ang balanse ng account"
}

404 Not Found

Hindi umiiral ang resource

404

{
  "code": "ORDER_NOT_FOUND",
  "message": "Hindi umiiral ang order"
}

409 Conflict

May salungatan sa resource

409

{
  "code": "ADDRESS_EXISTS",
  "message": "Umiiral na ang address"
}

429 Too Many Requests

Lumagpas sa rate limit ng API key

429

{
  "code": "RATE_LIMITED",
  "message": "Lumagpas sa rate limit"
}

500 Internal Server Error

Panloob na error ng server

500

{
  "code": "INTERNAL_ERROR",
  "message": "Naganap ang hindi inaasahang error"
}

503 Service Unavailable

Pansamantalang hindi available ang serbisyo (kasalukuyang nagre-restore)

503

{
  "code": "SERVICE_UNAVAILABLE",
  "message": "Pansamantalang hindi available ang serbisyo"
}

Mga Karaniwang Error Code

Error Code	Status	Description	Solution
UNAUTHORIZED	401	Mali, expired, o revoked na API key	Suriin kung tama ang API key, lumikha ng bago kung kinakailangan
INSUFFICIENT_BALANCE	403	Hindi sapat ang balanse ng account	Mag-recharge ng account
INVALID_ADDRESS	400	Mali ang format ng TRON address	Suriin kung wastong TRON address (nagsisimula sa T)
INVALID_ENERGY_AMOUNT	400	Mali ang halaga ng energy	Ang halaga ng energy ay dapat positibong integer, inirerekomenda ang 65000 para sa USDT transfer
INVALID_DURATION	400	Mali ang tagal ng rental	Gumamit ng wastong tagal: 1H, 1D, 3D, 7D, 14D, 30D
ORDER_NOT_FOUND	404	Walang order	Suriin kung tama ang order ID
ADDRESS_EXISTS	409	Umiiral na ang address	Suriin kung naidagdag na ang address o gamitin ang umiiral na address
RATE_LIMITED	429	Lumagpas sa rate limit ng API key (sa kasalukuyan ay inilalapat lang sa POST /v1/wallet/recharges)	Subukan muli na may exponential backoff o bawasan ang rate ng mga kahilingan

Mga Paraan ng Paghawak

Error	Handling
401 UNAUTHORIZED	Suriin/I-rotate ang API key
403 INSUFFICIENT_BALANCE	Mag-recharge o bawasan ang halaga ng kahilingan
409 ADDRESS_EXISTS	Lumipat sa query/idempotent processing
429 RATE_LIMITED	Subukan muli na may paghihintay (sundin ang Retry-After kung available, kung hindi gumamit ng exponential backoff)
5xx	Subukan muli + i-log ang konteksto ng kahilingan

Mga Gabay sa Pag-retry

• Maximum na pag-retry: 3 beses
• Paghihintay: exponential (1 segundo, 2 segundo, 4 segundo...)
• Subukan muli lang sa 429/5xx
• Huwag subukan muli sa 4xx (mga client-side error)

Mga Code ng Error at Paghawak