Error Code Reference

Response Format

Business errors can use the following envelope. Authentication and rate-limit responses may instead contain a flat error string; response shape depends on the deployed path. The safe error wrapper handles both without logging upstream text:

{
  "error": {
    "code": "E2001",
    "type": "game_not_found",
    "message": "Game Not Found",
    "details": {}
  }
}

Field	Type	Description
code	string	Stable error code (e.g., E2001). Use this for programmatic handling.
type	string	Snake-case name derived from the error enum. Treat the received value as untrusted; log only a recognized code.
message	string	Human-readable description. May include additional context.
details	object	Optional. Extra context such as field names, limits, or identifiers. Present only when relevant.

---

Provider Errors (E1xxx)

Errors related to game provider availability and configuration.

Code	Type	HTTP	Description	Operator Action
E1001	provider_not_found	404	Provider does not exist in the system.	Verify the provider_code you are sending 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 The Aggregator support for details.
E1004	provider_config_invalid	500	Provider configuration is broken or incomplete.	Contact The Aggregator support. This is a platform-side issue.

Provider Launch Errors (E1050-E1056)

These errors occur when launching a game through the provider wizard or test flow.

Code	Type	HTTP	Description	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 rate limit, not ours.
E1053	provider_launch_timeout	504	Provider did not respond in time.	Retry. If persistent, check 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 Errors (E1010-E1014)

Code	Type	HTTP	Description	Action
E1010	branding_upload_too_large	413	Uploaded branding asset exceeds the size limit.	Reduce file size and re-upload.
E1011	branding_invalid_file_type	400	File type is 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 have been uploaded yet.	Upload branding assets before proceeding.

Game Asset Errors (E1020-E1023)

Code	Type	HTTP	Description	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 is 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 has been reached.	Remove unused assets before uploading new ones.

---

Game Errors (E2xxx)

Errors related to game lookup and availability.

Code	Type	HTTP	Description	Operator 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 returned by 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 blocked_countries field on the game object.

---

Session Errors (E3xxx)

Errors related to game session lifecycle and player state.

Code	Type	HTTP	Description	Operator 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 (E4xxx)

Errors related to wallet callbacks and financial operations.

Code	Type	HTTP	Description	Operator Action
E4001	insufficient_balance	402	Player balance is too low for this bet amount.	Decline the bet with 402 (or HTTP 200 + body {"status": 402, ...}) and return the current balance in your callback response. The platform shows an insufficient-funds message to the player.
E4002	duplicate_transaction	200	This scoped transaction has already been processed (idempotent retry).	Replay the original response stored for this integration/organization, provider_code and transaction_id identity — same HTTP status (200 for a settled transaction) and body. Do not return 409 or re-process the transaction.
E4003	amount_exceeds_limit	400	Bet amount exceeds the configured maximum.	Check your operator limits. The details field includes the current limit.
E4004	invalid_amount	400	Amount is invalid for the transaction contract; supported zero-win settlements may use zero.	Validate the request amount against the transaction/provider contract.
E4005	loss_limit_exceeded	400	Player has hit their loss limit for the configured period.	The platform enforces this automatically. Do not allow further bets until the period resets.

---

Auth Errors (E5xxx)

Errors related to API key authentication, HMAC signature verification, and account deletion.

Code	Type	HTTP	Description	Operator Action
E5001	callback_signature_invalid	401	HMAC signature verification failed on a callback request.	Verify you are using the correct callback_secret and signing the request body correctly. See the signature verification guide.
E5002	api_key_invalid	401	API key is not recognized.	Check that you are sending the correct key in the Authorization header. Send the issued credential unchanged and confirm its status and deployment policy.
E5003	api_key_expired	401	API key has expired.	If your deployment returns this code, follow its credential replacement procedure; do not assume an expired key remains accepted.
E5004	scope_insufficient	403	This API key does not have permission for the requested operation.	Check the scopes assigned to your key. You may need a key with broader permissions.
E5020	deletion_blocked	409	Account deletion is blocked (active sessions or pending transactions).	Resolve all pending operations before requesting deletion.
E5021	deletion_failed	500	Account deletion encountered 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 deletion token and confirm within the time window.

---

Operator Config Errors (E6xxx)

Errors related to operator account setup and configuration.

Code	Type	HTTP	Description	Operator Action
E6001	operator_not_configured	400	No operator settings found for this provider integration.	Set up your callback_url in the operator cabinet before making API calls.
E6002	callback_url_invalid	400	The callback URL failed SSRF validation.	Use a publicly accessible HTTPS URL. Private IPs, localhost, and non-HTTPS URLs are rejected.
E6003	operator_disabled	403	Operator account has been disabled.	Contact The Aggregator support.

Platform accounts and brands (E6004–E6010)

These only occur on platform accounts — a partner whose single API key acts on behalf of several casino brands (“sub-operators”). Every operator-scoped call takes an optional sub_operator_ref naming the brand it acts as. An ordinary operator key never sees these.

Code	Type	HTTP	Description	Operator 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; sending it blank is an error, not a fallback.
E6005	sub_operator_required	400	The field was omitted, and this platform is configured with require_sub_operator_ref.	Name the brand on every call. This mode is opt-in — a platform running many brands can ask for a loud failure instead of a default.
E6006	sub_operator_not_allowed	400/403	sub_operator_ref was 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	This platform is at its brand cap.	Contact The Aggregator support to raise the cap.
E6008	sub_operator_unknown	400	An unseen ref, and auto-provisioning is disabled for this platform.	Create the brand first with POST /v1/sub-operators, or ask support to enable auto-provisioning.
E6009	platform_not_provisioned	409	The platform account is not fully set up and owns no organization to bill.	Contact The Aggregator 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 created becomes the default. A brand is never minted on the money path.

Omit the field, never send it empty

An absent sub_operator_ref resolves to your default brand. An empty one ("" or whitespace) is E6004.

The two differ on purpose. A field you never sent cannot have been meant to name a brand. A field you sent blank means your integration has the parameter and the value behind it came out empty — that request believes it selected a brand, and answering it with your default one would attribute the spins, and the bill, to a different brand while returning 201 as if nothing were wrong.

---

KYB / Organization Errors (E7xxx)

Errors related to Know Your Business verification and organization management.

Code	Type	HTTP	Description	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 has already been 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 in the KYB docs.
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 is 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 (E8xxx)

Errors related to team members, invitations, and role management within an organization.

Code	Type	HTTP	Description	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 – member already added.
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 has already been 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 do not have 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 to make this change.
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.	A user can only belong to one organization.
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 at the platform before accepting the invite.

---

Billing Errors (EBxxx)

Errors related to billing, payments, and package purchases.

Code	Type	HTTP	Description	Action
EB001	billing_kyb_required	403	KYB verification must be completed before billing.	Complete the KYB process first.
EB002	billing_aml_cap_exceeded	400	Transaction exceeds 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.	Wait for the next billing period.
EB006	billing_payment_failed	400	Payment processing failed.	Check payment method details and retry.
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 has been 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	Billing webhook payload is invalid.	Check the webhook signature and payload format.

---

Affiliate Errors (EAxxx)

Errors related to the affiliate/referral program.

Code	Type	HTTP	Description	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 affiliate link.	Retry or contact support.

---

Rate Limiting (E9xxx)

Code	Type	HTTP	Description	Operator Action
E9001	rate_limited	429	Too many requests. The exact envelope and budget attribution depend on the deployed rate policy.	Respect supplied Retry-After and rate-limit headers; do not assume every response includes each header. See Authentication → Rate limits.

---

Internal Errors (E0xxx)

Code	Type	HTTP	Description	Operator Action
E0001	internal_error	500	Unexpected server error.	Retry with exponential backoff. If the error persists for more than 5 minutes, contact support with the HTTP status, recognized error code, and a correlation ID generated by your application.
E0002	database_error	503	Database connectivity issue. This is transient.	Retry after a short delay. These errors typically resolve within seconds.

---

HTTP Status Code Summary

For quick reference, here is how error codes map to HTTP status codes:

HTTP Status	Meaning	Error Code Ranges
400	Bad Request	E4003, E4004, E4005, E6001, E6002, E6004, E6005, E6006, E6007, E6008, E7003-E7005, E7008, E7012, E8006, E8011, E8014, E8018, E8020, E8022, EB002, EB005, EB006, EB008, EB010, EB011, EA002, EA005, EA006
401	Unauthorized	E5001, E5002, E5003, E1050
402	Payment Required	E4001
403	Forbidden	E1003, E2002, E2003, E3004, E5004, E6003, E6006, E8009, E8010, EB001, EA001
404	Not Found	E1001, E2001, E3001, E7001, E7007, E7009, E7013, E7015, E8001, E8003, E8007, EB003, EB004, EB007, E1012, E1014, E1022
409	Conflict	E5020, E6009, E6010, E7002, E7006, E8002, E8005, E8008, E8013, E8021, 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
504	Gateway Timeout	E1053

---

Best Practices for Error Handling

1. Match on code, not message. The message field may change between versions. The code field is stable.
2. Log safe diagnostics. Record the HTTP status and only error codes your application explicitly recognizes; map unexpected codes to a fixed label. The response body, message, and details may contain sensitive data: keep them out of logs. When contacting support, include a correlation ID generated by your application.
3. Retry transient errors. Codes E0001, E0002, E1002, E1053, and E1054 are transient. Use exponential backoff with jitter.
4. Do not retry 4xx errors. Client errors (400, 401, 402, 403, 404, 409) indicate a problem with the request (or, for 402, a declined bet). Fix the request before retrying.
5. Respect rate limit headers. Use supplied Retry-After and X-RateLimit-* values; retry only when the operation’s idempotency contract permits it.
6. Handle E4002 (duplicate) gracefully. This is expected in idempotent retry flows. Return the same response you returned for the original transaction.