Errors and Error Responses

1. Error Response Shape

All failed requests return a unified structure:

{
  "error": true,
  "code": 400,
  "message": "Bad Request"
}

Field definitions:

error: always true.

code: defaults to the HTTP status code; if business logic explicitly sets code, that value is returned.

message: human-readable error message string.

HTTP Status	Default `code`	Meaning
400	400	Invalid request params or DSL rule violations
401	401	Missing, invalid, or expired `x-api-key`
403	403	API key exists but is not allowed (for example, inactive)
500	500	Internal server error

Most of the following come from POST /api/v1/open-api/geo/analysis:

message	Trigger condition
`entity required`	Missing `target.entity`
`analysis.type required`	Missing `analysis.type`
`analysis.type not supported: <type>`	Unsupported analysis type
`metrics required`	Missing or empty `target.metrics`
`entity not supported`	Unsupported entity
`metric not supported: <metric>`	Unsupported metric
`metric not supported by entity: <metric>`	Metric/entity mismatch
`metric not supported by analysis: <metric>`	Metric/analysis-type mismatch
`ranking.orderBy must be included in metrics`	`orderBy` is not included in `metrics`
`ranking.direction invalid`	Direction is not `asc` or `desc`
`correlation requires exactly 2 metrics`	Correlation must contain exactly 2 metrics
`distribution requires exactly 1 metric`	Distribution must contain exactly 1 metric
`matrix requires exactly 1 metric`	Matrix must contain exactly 1 metric
`matrix requires entity: platform`	Matrix supports `platform` entity only
`matrix requires analysis.matrix.rowDimension (brand or topic)`	Missing matrix `rowDimension`
`ai_mention is not supported for matrix analysis`	`ai_mention` is not allowed in matrix analysis

Type/validation mismatches in query/body can also return 400. Typical cases:

Invalid ISO datetime values (for example, startAt / endAt).

Non-numeric pagination values (for example, page / pageSize).

Enum values outside allowed range (for example, sortOrder must be 1 or -1).

First classify by HTTP status (401 / 403 / 400 / 500).

Log code + message + requestId (if available).

Do not retry 401/403; use limited exponential-backoff retries for 500.