Error Codes & Troubleshooting

FFData employs standard HTTP status codes combined with unique, fine-grained integer error codes for accurate client-side exception routing.

API Errors

Error Code	Message Name	HTTP Status	Description
1001	CLAN_NOT_FOUND	404	The requested Clan/Guild ID does not exist in Garena databases.
1002	PLAYER_NOT_FOUND	404	The target Player account UID does not exist or has been deleted.
4001	UNAUTHORIZED	401	API key is missing, corrupted, or has expired.
4003	INSUFFICIENT_CREDITS	403	Account has 0 or insufficient credits left. Add more balance to resume.
4029	RATE_LIMIT_EXCEEDED	429	Client IP or API key has exceeded request limits. Retry after delay.

SDK Errors

The official Python SDK maps the raw API errors into structured exceptions:

AuthError

Raised when requests fail due to invalid or expired credentials (401 Status).

InsufficientCreditsError

Raised when developer accounts have insufficient credit allocations to process query actions (403 Status).

RateLimitError

Raised when requests exceed rate boundaries. Access the cooldown period using the `.retry_after` parameter.

CircuitBreakerError

Triggered client-side when the target endpoint experiences high failure rates, preventing wasteful network calls.

Website & Frontend Errors

The developer dashboard utilizes toast messages and state wrappers to display issues. Common frontend codes include:

FED_AUTH_01: Failed to exchange Google authentication state with local sessions.
FED_KEY_02: Unsuccessful attempt to create or refresh active API credentials.
FED_PAY_03: Stripe/Billing checkout session registration failure.

Internal System Errors

Errors in the `5xx` range indicate internal server faults. In these scenarios, the circuit breakers automatically open client-side and trigger backoff retries.

GATEWAY_TIMEOUT (504): Upstream Garena networks failed to acknowledge request within 10 seconds.
INTERNAL_DECRYPTION_FAILED (500): The server failed to parse the encrypted protocol buffer stream response.

Debugging & Tracing

Each error payload returns a unique uuid labeled `request_id`. When reaching out for support or filing tickets, please provide the exact `request_id` to assist in server-side log tracing.

Sample Error Payload

json

{
  "success": false,
  "error": "CLAN_NOT_FOUND",
  "error_code": 1001,
  "meta": {
    "time_ms": 12,
    "request_id": "f1a71b57-c8f8-4816-a8c8-e7a9f0eccd65"
  }
}
  }
}