Error Codes

The new Client API usually returns business errors with HTTP 200:

{
  "code": 0,
  "body": null,
  "error_code": 471,
  "error_message": "Coupon not found",
  "date": 1784970000000,
  "time_ms": 5,
  "path": "/api/partner/coupons/get"
}

Check:

HTTP status → transport result
code        → business operation result
error_code  → specific error reason

Do not use error_message as a programmatic identifier.

New API Summary Table

“No” means that the request, data, or cause of the error must be corrected first.

Authentication Errors

HTTP 401

For protected new API routes, this means:

• the JWT is missing;
• the JWT has an invalid format or signature;
• the token expired;
• the token was revoked.

Action:

1. call POST /api/partner/login;
2. obtain a new body.token;
3. retry a safe read request.

After 401 during coupon creation, first make sure the original request was not accepted.

HTTP 403

This means that:

• the token does not have the client role;
• an administrative JWT is being used;
• account access is denied.

Logging in again with the same incorrect account or token type will not fix the problem. Check the account and contact the manager if necessary.

POST /api/partner/login Business Errors

All listed responses use HTTP 200 and code = 0:

Unknown usernames and incorrect passwords are intentionally not distinguished and both return 1003.

In the legacy API, 1003 has a different meaning: an invalid JWT on a protected route. Legacy login maps every authentication rejection to code 99. Always consider the route.

Request Errors

10 — Required Data Is Missing

Possible examples:

• no JSON body was sent for coupon creation;
• no code was sent to /api/partner/coupons/get.

For the new POST /api/partner/login, a missing username or password is the separate business error 1002.

Check the required fields for the specific endpoint.

11 — Invalid Pointer

At least one list_bets entry does not match:

line_type#game_id#group_id#type_id#rate#coefficient[#player_id]

Action:

• do not treat the coupon as accepted;
• do not make the final deduction;
• obtain a current ready-made pointer from the feed;
• do not try to repair the pointer using outcome names.

12 — Invalid Amount

amount is absent, has an incompatible type, or is not positive.

Validate before submitting:

amount > 0

1002 — Invalid Parameter Set

Used in particular for /api/partner/coupons/results when:

• both coupon_ids and dates are provided;
• only one date boundary is provided;
• the period is not positive;
• the period exceeds 24 hours;
• the request mode cannot be determined.

Correct the parameters. Retrying the unchanged request returns the same error.

Outcome Validation Errors

The new /api/partner/coupons/place returns problematic bets in:

body.changes[]

Common Format

{
  "code": 0,
  "body": {
    "changes": [
      {
        "game_id": 737779544,
        "bet_coefficient": 2.19,
        "actual_coefficient": 2.09,
        "change_type": 2,
        "status": "rejected"
      }
    ]
  },
  "error_code": 501,
  "error_message": "Coefficient is change"
}

501 — Odds Changed

status = rejected
change_type = 1 or 2

Action:

• do not treat the coupon as accepted;
• show the current odds to the user;
• obtain confirmation when required by partner rules;
• or use a pre-agreed mode = accept.

502 — Outcome Is Absent

status = no_data
change_type = null

The outcome is no longer present in the current feed. Remove or update it in the bet slip.

503 — Outcome Is Blocked

status = block
change_type = null

Bet acceptance is temporarily unavailable. Do not store the coupon as accepted.

504 — Validation Error

status = error
change_type = null

Validation of this outcome did not complete successfully. Do not treat this as bet confirmation. Refresh the feed and offer another attempt later.

Important. Business codes 502, 503, and 504 inside JSON are not HTTP statuses 502, 503, and 504. Always distinguish error_code from the HTTP status.

506 — Bets from the Same Match

An accumulator contains multiple outcomes from one match, including the main event and related sub-events.

For example:

• match and corners;
• corners and fouls;
• different periods of the same match.

Keep only one outcome from the match tree, or create separate singles using multi = true.

507 — Insufficient Balance

{
  "code": 0,
  "error_code": 507,
  "error_message": "Insufficient balance",
  "date": 1753000000000,
  "time_ms": 5,
  "path": "/api/partner/coupons/place"
}

The total client account balance is insufficient to create the coupon or all singles requested with multi = true.

The operation is atomic:

• no coupon is created;
• the client balance does not change;
• partial success with multi = true is impossible.

Retry only after funding the client balance or deliberately reducing the total amount. A positive balance may permit login but still be insufficient for a specific creation request: login then succeeds, while creation returns 507.

Coupon Read Errors

471 — Coupon Not Found

The new /api/partner/coupons/get returns the same error when:

• the code does not exist;
• the coupon belongs to another partner.

This prevents the API from disclosing the existence of another partner’s data.

Action:

• check coupon_code;
• make sure leading zeros were preserved;
• make sure the JWT belongs to the correct client account.

Do not create an empty local record in place of an existing coupon.

Internal Error

10000

Indicates an internal service error.

Read requests may be retried with rate limiting.

Do not blindly retry POST /api/partner/coupons/place after an indeterminate result. First rule out the possibility that the original request was processed, otherwise a duplicate coupon may be created.

If the error persists, provide the manager with:

• the route;
• request time;
• coupon_code, if known;
• top-level date, path, and time_ms;
• a safe request identifier from the partner logs.

Do not provide a JWT, password, or callback secret.

New API HTTP Errors

HTTP 200 with code = 0 is a business error and must be processed by error_code.

Callback Errors

Callbacks do not use error_code. The receiver reports the result through its HTTP response.

Only HTTP 200 is a successful acknowledgement. Responses 201, 202, and 204 are not considered successful and are not retried automatically.

Legacy API Codes

Legacy POST /bet/place preserves the same code for rejected, no_data, block, and error:

error_code = 501

The exact reason is in the direct body[] array.

Historical documentation associated 507 with a general server error. In the current 1.2.0 contract, it has the defined meaning Insufficient balance; process it as insufficient client balance. Code 540 is historical and is not part of the current OpenAPI contract.

See Compatible Legacy Routes for details.

What to Show the User

Do not show the user:

• JWT;
• password;
• callback secret;
• internal stack traces;
• infrastructure details;
• complete signed callbacks.

Checklist

• HTTP status, code, and error_code are checked.
• error_message is not used as a logic key.
• When creation is rejected, the coupon is not stored as accepted.
• Any preliminary amount reservation is released after a confirmed rejection.
• body.changes is processed as an array.
• Business codes 502–504 are not confused with HTTP statuses.
• Error 506 is handled in the accumulator bet slip.
• Creation requests are not retried blindly.
• Callback errors are handled through their separate HTTP contract.
• Secret data is not included in messages or logs.

Next section: Migrating from the Legacy API.