Skip to content
The Aggregator

Error Code Reference

Response Format

Section titled “Response Format”

All error responses return a JSON body with the following structure:

{
  "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. Useful for logging.
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)

Section titled “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)

Section titled “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)

Section titled “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)

Section titled “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)

Section titled “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)

Section titled “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)

Section titled “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 transaction ID has already been processed (idempotent retry). Replay the original response you sent for this transaction_id — 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 negative, zero, or not a valid number. Fix the amount value in your callback response.
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)

Section titled “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. All operator keys are prefixed sk_live_*.
E5003 api_key_expired 401 API key has expired. Generate a new API key in the operator cabinet under Settings > API Keys.
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)

Section titled “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)

Section titled “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.

KYB / Organization Errors (E7xxx)

Section titled “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)

Section titled “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)

Section titled “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)

Section titled “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)

Section titled “Rate Limiting (E9xxx)”
Code Type HTTP Description Operator Action
E9001 rate_limited 429 Too many requests. You have exceeded a rate-limit bucket — the scope field on the error body identifies which (key, user, key_write, user_write). Check the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset response headers. See Authentication → Rate limits for the full bucket table. Implement exponential backoff.

Internal Errors (E0xxx)

Section titled “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 X-Request-Id header from the response.
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

Section titled “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

Section titled “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 the full error body. Include code, type, and details in your logs for debugging.
  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. When you receive E9001, read X-RateLimit-Reset to know when you can resume requests.
  6. Handle E4002 (duplicate) gracefully. This is expected in idempotent retry flows. Return the same response you returned for the original transaction.