Error Codes

This page documents the exact error responses returned by the Ruby API.

Response Shapes

The API uses two distinct response shapes depending on the error type.

Business Errors (401 / 404 / 409)

The detail field is a string.

{
  "detail": "<error message>"
}

Validation Errors (422)

The detail field is an array of objects describing each validation failure.

{
  "detail": [
    {
      "loc": ["body", "field_name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

401 — Authentication Failures

All authentication failures return HTTP 401. The detail value is one of the following strings, exactly as returned by the server.

`detail` value	Meaning	Resolution
`无效的 API Key`	API key not found in the system	Verify the `X-Team-Key` header value
`无效的时间戳格式`	Timestamp is not a valid integer	Send `X-Team-Timestamp` as a Unix epoch integer (e.g. `1712345678`)
`请求时间戳超出允许范围（±300秒）`	Timestamp is outside the ±300-second window	Sync your system clock; ensure the request is sent promptly
`签名验证失败`	HMAC-SHA256 signature does not match	Re-check the signing algorithm and string construction
`Team 已禁用`	The team account has been disabled	Contact support to re-enable the team account

404 — Resource Not Found

HTTP 404 is returned when the requested resource does not exist or does not belong to the authenticated team.

Endpoint	`detail` value	Condition
`GET /api/player/{id}`	`玩家不存在`	Player ID not found
`GET /api/bet/{id}`	`注单不存在`	Bet record ID not found
`GET /api/sports-bet/{id}`	`体育注单不存在`	Sports bet record ID not found
`PUT /api/provider-limit/team/{provider_id}`	`游戏商不存在`	Provider ID not found
`GET /api/provider-limit/brand/{brand_id}`	`品牌不存在`	Brand ID not found or not owned by team
`PUT /api/provider-limit/brand/{brand_id}/{provider_id}`	`品牌不存在`	Brand ID not found or not owned by team
`PUT /api/provider-limit/brand/{brand_id}/{provider_id}`	`游戏商不存在`	Provider ID not found

409 — Conflict

HTTP 409 is returned when a uniqueness constraint is violated.

Endpoint	`detail` value	Condition
`POST /api/brand/create`	`品牌代码 '{code}' 已存在`	A brand with the same `code` already exists for this team. `{code}` is replaced with the actual submitted value.

422 — Validation Error

HTTP 422 is returned by FastAPI when the request body or query parameters fail schema validation. The detail field is an array; each element describes one invalid field.

Example — missing required field:

{
  "detail": [
    {
      "loc": ["body", "code"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Example — multiple validation failures:

{
  "detail": [
    {
      "loc": ["body", "min_bet"],
      "msg": "value is not a valid decimal",
      "type": "type_error.decimal"
    },
    {
      "loc": ["query", "page"],
      "msg": "ensure this value is greater than or equal to 1",
      "type": "value_error.number.not_ge"
    }
  ]
}

Future improvement

Structured English error codes (e.g. INVALID_API_KEY, PLAYER_NOT_FOUND) are planned for a future release. The current API returns Chinese-language detail strings.

Response Shapes​

Business Errors (401 / 404 / 409)​

Validation Errors (422)​

401 — Authentication Failures​

404 — Resource Not Found​

409 — Conflict​

422 — Validation Error​