Error reference

Named conditions from the current Core/App error enums, grouped by family. This is a compatibility catalogue, not a claim that every condition is emitted by the machine API: cabinet-only and retired entries are included. Endpoint-specific flat errors also exist. The envelope these codes arrive in, and the rules for retrying, are on Errors; this page is the lookup table.

How to use this reference

• Match on code, not message. Messages may change between versions; codes are stable.
• Keep diagnostics fixed. Log HTTP status and an allowlisted code with your local correlation ID. Never log raw bodies, types, details or upstream messages.
• Retry only transient codes. E0001, E0002, E1002, E1053, E1054, with exponential backoff and jitter. Most request errors need correction; 429 and 409 idempotency_in_progress need bounded pacing with the same key and body. Reconcile an ambiguous operation before starting another one.
• Treat 402 as business, not failure. E4001 is a declined bet; handle it in the callback decline flow.
• Treat E4002 as success replayed. Return the original response for the duplicate trusted integration/organization + provider + transaction identity; do not return 409 and do not process again.

Provider errors

Availability and configuration of game providers (E1xxx).

Code	Type	HTTP	Description	Your action
E1001	provider_not_found	404	Provider does not exist in the system.	Verify the provider_code matches a registered provider.
E1002	provider_unavailable	502	Provider is temporarily unreachable.	Retry after a short delay with exponential backoff.
E1003	provider_suspended	403	Provider has been suspended by the platform.	Contact Aggregator.gg support for details.
E1004	provider_config_invalid	500	Provider configuration is broken or incomplete.	Contact Aggregator.gg support; this is platform-side.

Launch-time provider errors (E1050-E1056), raised when a game launch reaches the provider:

Code	Type	HTTP	Description	Your action
E1050	provider_launch_auth_failed	401	Authentication with the provider failed.	Check provider API credentials in your configuration.
E1051	provider_launch_game_not_found	404	The provider does not recognize this game.	Verify the game exists in the provider’s catalog.
E1052	provider_launch_rate_limited	429	Provider-side rate limit hit.	Wait and retry; this is the provider’s limit, not Aggregator.gg’s.
E1053	provider_launch_timeout	504	Provider did not respond in time.	Retry; if persistent, check the provider status page.
E1054	provider_launch_unavailable	502	Provider launch endpoint is down.	Retry after a delay; check provider status.
E1055	provider_launch_no_url	502	Provider returned a response but no launch URL.	Contact support; likely a provider-side issue.
E1056	provider_launch_unsafe_url	502	Provider returned a URL that failed safety validation.	Contact support.

Branding assets (E1010-E1014):

Code	Type	HTTP	Description	Your action
E1010	branding_upload_too_large	413	Branding asset exceeds the size limit.	Reduce file size and re-upload.
E1011	branding_invalid_file_type	400	File type not accepted for branding assets.	Use a supported format (PNG, SVG, JPEG).
E1012	branding_profile_not_found	404	Branding profile does not exist.	Create a branding profile first.
E1013	branding_processing_in_progress	409	A branding upload is already being processed.	Wait for the current upload to finish.
E1014	branding_no_assets	404	No branding assets uploaded yet.	Upload branding assets before proceeding.

Game assets (E1020-E1023):

Code	Type	HTTP	Description	Your action
E1020	game_asset_upload_too_large	413	Game asset file exceeds the size limit.	Reduce file size and re-upload.
E1021	game_asset_invalid_file_type	400	File type not accepted for game assets.	Use a supported format.
E1022	game_asset_not_found	404	Requested game asset does not exist.	Verify the asset ID.
E1023	game_asset_limit_exceeded	400	Maximum number of assets per game reached.	Remove unused assets before uploading new ones.

Game errors

Game lookup and availability (E2xxx).

Code	Type	HTTP	Description	Your action
E2001	game_not_found	404	Game ID does not exist or is not enabled for your account.	Verify the game_id against the catalog from GET /v1/games.
E2002	game_not_enabled	403	Game exists in the catalog but is currently disabled.	Choose a different game or contact support to enable it.
E2003	game_blocked_jurisdiction	403	Game is not available in the player’s jurisdiction.	Do not offer this game to players in the blocked country; check the game’s blocked_countries field.

Session errors

Session lifecycle and player state (E3xxx).

Code	Type	HTTP	Description	Your action
E3001	session_not_found	404	Session does not exist or belongs to a different operator.	Verify the session_id; sessions are scoped to your API key.
E3002	session_expired	410	Session has expired; sessions have a 24-hour lifetime.	Create a new session via POST /v1/sessions.
E3003	session_limit_exceeded	429	Too many concurrent sessions for this operator.	Complete or expire existing sessions before creating new ones.
E3004	player_self_excluded	403	Player is on the self-exclusion list.	Do not allow this player to play; this is a regulatory requirement.

Transaction errors

Wallet callbacks and financial operations (E4xxx).

Code	Type	HTTP	Description	Your action
E4001	insufficient_balance	402	Two situations share this code; see the note below the table. On a wallet callback: the player’s balance is too low for this bet. On POST /v1/sessions: the organization’s credit balance is exhausted.	Callback: decline the bet with 402 (or HTTP 200 plus body {"status": 402, ...}) and return the current balance; the platform shows the player an insufficient-funds message. Session launch: top up your organization’s credits in the cabinet.
E4002	duplicate_transaction	200	This transaction ID was already processed (idempotent retry).	Replay the original response for this scoped integration/organization + provider + transaction identity, same status and body. Do not return 409 or re-process.
E4003	amount_exceeds_limit	400	Bet amount exceeds the configured maximum.	Check your operator limits; details includes the current limit.
E4004	invalid_amount	400	An amount is invalid for this operation; zero free wins are a supported case.	Validate the relevant request field and transaction type; do not reject every zero amount.
E4005	loss_limit_exceeded	400	Player hit their loss limit for the configured period.	Enforced automatically by the platform; do not allow further bets until the period resets.

E4001 is one code with two contexts and opposite reactions: branch on which endpoint answered with the 402, never on the code alone. On a wallet callback it is the player’s problem: you decline the bet, no debit should be committed for the declined bet. Provider error/recovery mapping is integration-specific. On POST /v1/sessions (live launches only) it is your organization’s problem: the credit balance has reached its overdraft floor, new launches are refused with 402 until you top up credits in the cabinet, and in-flight sessions keep settling in the meantime. Neither case is a retry candidate.

Authentication errors

API keys, HMAC signatures, and account deletion (E5xxx). Note that live API-key rejections currently answer with a flat body, {"error": "invalid_token", "message": "API key authentication failed"}, without a code field; the E5002/E5003 rows below name the catalogued conditions, and you match them on the HTTP 401. See Errors.

Code	Type	HTTP	Description	Your action
E5001	callback_signature_invalid	401	HMAC verification failed on a callback request.	Verify you use the correct callback_secret and sign the raw body; see Request signatures.
E5002	api_key_invalid	401	API key is not recognized.	Check the Authorization header; new operator keys start with agg_; see API keys for legacy compatibility.
E5003	api_key_expired	401	Retired on 26 August 2026: keys do not expire and authentication does not read the expiry date, so this condition is no longer raised.	Nothing to do. If a key stops authenticating, it was revoked or deprecated; see API keys.
E5004	scope_insufficient	403	This key lacks permission for the requested operation.	Ask your account contact to adjust the key’s permissions.
E5020	deletion_blocked	409	Account deletion blocked (active sessions or pending transactions).	Resolve all pending operations before requesting deletion.
E5021	deletion_failed	500	Account deletion hit an unexpected error.	Retry or contact support.
E5022	deletion_token_invalid	400	The deletion confirmation token is invalid.	Request a new deletion token.
E5023	deletion_token_expired	400	The deletion confirmation token has expired.	Request a new token and confirm within the window.

Operator configuration errors

Operator account setup (E6001-E6003) and platform accounts (E6004-E6010).

Code	Type	HTTP	Description	Your action
E6001	operator_not_configured	400	No operator settings found for this provider integration.	Verify provider enablement and wallet configuration; platform accounts may need assisted shared-wallet setup.
E6002	callback_url_invalid	400	The callback URL failed SSRF validation.	Use a publicly accessible HTTPS URL; private IPs, localhost, and non-HTTPS are rejected.
E6003	operator_disabled	403	Operator account has been disabled.	Contact Aggregator.gg support.

These codes describe platform brand selection. An ordinary operator that incorrectly supplies sub_operator_ref can receive E6006; the model behind them is on Platform accounts.

Code	Type	HTTP	Description	Your action
E6004	sub_operator_ref_invalid	400	sub_operator_ref is malformed, or was sent empty.	Use 1-32 characters of [A-Za-z0-9_-], starting and ending alphanumeric. To use your default brand, omit the field entirely; a blank value is an error, not a fallback.
E6005	sub_operator_required	400	The field was omitted and this platform runs require_sub_operator_ref.	Name the brand on endpoints that accept the selector; strict mode is opt-in for platforms that prefer a loud failure over a default.
E6006	sub_operator_not_allowed	400/403	sub_operator_ref sent from a key that is not a platform key.	Remove the field; your key already identifies a single operator.
E6007	sub_operator_limit	400/503	Brand cap reached, or its count could not be verified.	Contact support for the cap; retry a transient 503 with bounded backoff.
E6008	sub_operator_unknown	400/403	Ref cannot be provisioned or resolved, or brand is inactive.	Confirm the registered active brand. Explicit creation uses the same provisioning policy; contact support if disabled.
E6009	platform_not_provisioned	409	The platform account is not fully set up and owns no organization to bill.	Contact Aggregator.gg support.
E6010	platform_default_missing	409	A call omitted sub_operator_ref and this platform has no default brand.	Create your first brand with POST /v1/sub-operators; the first one becomes the default. An omitted ref never creates the first brand; explicit unknown refs can auto-provision when policy allows.

KYB and organization errors

Know Your Business verification and organization management (E7xxx). The current cabinet starts review automatically when the record becomes complete. Its old manual submit endpoint returns 410 with flat kyb_submit_retired; historical submission-related enum entries below do not describe a current submit button.

Code	Type	HTTP	Description	Your action
E7001	org_not_found	404	Organization does not exist.	Check the organization ID.
E7002	org_already_exists	409	An organization with this identifier already exists.	Use the existing organization or choose a different name.
E7003	kyb_not_submittable	400	KYB application is not in a submittable state.	Complete all required fields before submitting.
E7004	kyb_documents_incomplete	400	Required KYB documents are missing.	Upload all required documents.
E7005	kyb_ubo_incomplete	400	Ultimate Beneficial Owner information is incomplete.	Provide all required UBO details.
E7006	kyb_already_submitted	409	KYB application already submitted for review.	Wait for the review to complete.
E7007	kyb_doc_not_found	404	KYB document not found.	Verify the document ID.
E7008	kyb_doc_not_deletable	400	Document cannot be deleted in the current KYB state.	Documents cannot be removed after submission.
E7009	kyb_ubo_not_found	404	UBO record not found.	Verify the UBO ID.
E7010	kyb_invalid_status_transition	400	Invalid KYB status transition.	Check the allowed status transitions.
E7011	kyb_upload_too_large	413	KYB document exceeds the upload size limit.	Reduce file size and re-upload.
E7012	kyb_invalid_file_type	400	File type not accepted for KYB documents.	Use PDF, PNG, or JPEG.
E7013	kyb_officer_not_found	404	KYB officer record not found.	Verify the officer ID.
E7014	kyb_screening_failed	500	Automated screening encountered an error.	Retry or contact support.
E7015	kyb_review_not_found	404	KYB review record not found.	Verify the review ID.

Member management errors

Team members, invitations, and roles (E8xxx).

Code	Type	HTTP	Description	Your action
E8001	member_not_found	404	Team member not found.	Verify the member ID.
E8002	member_already_exists	409	User is already a member of this organization.	No action needed.
E8003	invite_not_found	404	Invitation not found.	Verify the invite token or ID.
E8004	invite_expired	410	Invitation has expired.	Send a new invitation.
E8005	invite_already_accepted	409	Invitation already accepted.	No action needed.
E8006	invite_email_mismatch	400	The accepting user’s email does not match the invite.	Accept with the email address the invite was sent to.
E8007	join_request_not_found	404	Join request not found.	Verify the request ID.
E8008	join_request_duplicate	409	A join request from this user already exists.	Wait for the existing request to be reviewed.
E8009	role_change_forbidden	403	You lack permission to change this role.	Only owners and admins can modify roles.
E8010	cannot_modify_higher_role	403	You cannot modify a member with a higher role than yours.	Ask an owner to make this change.
E8011	cannot_modify_self	400	You cannot modify your own role or status.	Ask another admin or owner.
E8012	transfer_failed	500	Ownership transfer failed.	Retry or contact support.
E8013	member_already_suspended	409	Member is already suspended.	No action needed.
E8014	member_not_active	400	Member is not in an active state.	Reactivate the member first.
E8017	invite_rate_limited	429	Too many invitations sent in a short period.	Wait before sending more invitations.
E8018	last_owner_cannot_leave	400	The last owner cannot leave the organization.	Transfer ownership before leaving.
E8019	user_already_in_org	409	User already belongs to an organization.	Check existing membership and the target organization context before retrying.
E8020	join_code_invalid	400	The join code is invalid or expired.	Request a fresh join code from an admin.
E8021	transfer_pending	409	An ownership transfer is already in progress.	Wait for the current transfer to complete.
E8022	invite_registration_required	400	The invited user must register an account first.	Register before accepting the invite.
E8023	invite_not_resendable	409	A pending invitation cannot be resent through this channel.	For a Telegram invite, revoke it and create a new link in the supported Mini App flow.

Billing errors

Billing, payments, and package purchases (EBxxx).

Code	Type	HTTP	Description	Your action
EB001	billing_kyb_required	403	A billing operation requires additional KYB clearance.	Follow the actual cabinet condition; this enum is not a universal gate on registration, key issuance or every purchase.
EB002	billing_aml_cap_exceeded	400	Transaction exceeds the AML compliance cap.	Contact support for limit increases.
EB003	billing_package_not_found	404	Billing package does not exist.	Verify the package ID.
EB004	billing_purchase_not_found	404	Purchase record not found.	Verify the purchase ID.
EB005	billing_purchase_limit	400	Purchase limit reached for this package.	Check the applicable package purchase limit in the cabinet; do not assume a monthly reset.
EB006	billing_payment_failed	400	Payment processing failed.	Check the recorded purchase and payment outcome before paying again; use support for ambiguity.
EB007	billing_invoice_not_found	404	Invoice not found.	Verify the invoice ID.
EB008	billing_insufficient_balance	400	Insufficient billing balance.	Top up your account balance.
EB009	billing_manual_review	202	Transaction flagged for manual review.	Wait for review to complete; you will be notified.
EB010	billing_offer_not_accepted	400	The billing offer has not been accepted.	Accept the offer terms before proceeding.
EB011	billing_webhook_invalid	400	A payment-processor notification failed validation on the platform side.	Check the existing purchase status and contact support; do not send a second payment merely because a processor notification failed.
EB012	billing_tx_hash_already_used	409	The transaction hash is already claimed by another purchase.	Reconcile the existing purchase; do not reuse the hash for another credit.

Affiliate errors

The affiliate and referral program (EAxxx).

Code	Type	HTTP	Description	Your action
EA001	affiliate_not_eligible	403	Account is not eligible for the affiliate program.	Check eligibility requirements.
EA002	affiliate_insufficient_balance	400	Affiliate balance is too low for withdrawal.	Wait for more earnings to accumulate.
EA003	affiliate_withdrawal_rate_limited	429	Too many withdrawal requests.	Wait before requesting another withdrawal.
EA004	affiliate_withdrawal_failed	500	Withdrawal processing failed.	Retry or contact support.
EA005	affiliate_invalid_wallet	400	Provided wallet address is invalid.	Check the wallet address format.
EA006	affiliate_below_min_withdrawal	400	Amount is below the minimum withdrawal threshold.	Check the minimum withdrawal amount in settings.
EA007	affiliate_withdrawal_pending_approval	202	Withdrawal is pending manual approval.	Wait for approval; you will be notified.
EA008	affiliate_link_failed	500	Failed to generate the affiliate link.	Retry or contact support.

Rate limiting errors

The request limiter has an E9xxx catalogue entry; its deployed rejection body is flat. Session, provider and grant limits have separate responses.

Code	Type	HTTP	Description	Your action
E9001	rate_limited	429	Too many requests: a rate-limit bucket is exhausted. The response body’s scope field names the bucket, key or user.	Read X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After, then back off; the buckets, numbers, and headers are specified in Rate limiting.

Internal errors

Platform-side failures (E0xxx).

Code	Type	HTTP	Description	Your action
E0001	internal_error	500	Unexpected server error.	Retry with exponential backoff; if it persists past 5 minutes, contact support with reviewed correlation evidence, keeping secrets and raw responses out of the report.
E0002	database_error	503	Database connectivity issue; transient.	Retry after a short delay; these typically resolve within seconds.

HTTP status map

Common status mappings for the catalogue above. Endpoint-specific flat errors and retired conditions are not an exhaustive status index.

HTTP status	Meaning	Error codes
400	Bad Request	E4003, E4004, E4005, E6001, E6002, E6004, E6005, E6006, E6007, E6008, E7003-E7005, E7008, E7010, E7012, E8006, E8011, E8014, E8018, E8020, E8022, E5022, E5023, EB002, EB005, EB006, EB008, EB010, EB011, EA002, EA005, EA006, E1011, E1021, E1023
401	Unauthorized	E5001, E5002, E5003, E1050
402	Payment Required	E4001
403	Forbidden	E1003, E2002, E2003, E3004, E5004, E6003, E6006, E6008, E8009, E8010, EB001, EA001
404	Not Found	E1001, E2001, E3001, E7001, E7007, E7009, E7013, E7015, E8001, E8003, E8007, EB003, EB004, EB007, E1012, E1014, E1022, E1051
409	Conflict	E5020, E6009, E6010, E7002, E7006, E8002, E8005, E8008, E8013, E8019, E8021, E8023, EB012, E1013
410	Gone	E3002, E8004
413	Payload Too Large	E1010, E1020, E7011
429	Too Many Requests	E3003, E9001, E1052, E8017, EA003
500	Internal Server Error	E0001, E1004, E5021, E7014, E8012, EA004, EA008
502	Bad Gateway	E1002, E1054, E1055, E1056
503	Service Unavailable	E0002, E6007
504	Gateway Timeout	E1053

Step check: pick any code your integration has actually received, look it up here, and confirm your handler does what the “Your action” column says, not something the message text once suggested.