Skip to content

errors.md

Latest commit

 

History

History
589 lines (388 loc) · 7.65 KB

errors.md

File metadata and controls

589 lines (388 loc) · 7.65 KB
Raw

Errors

This document describes known HTTP status codes and error responses returned by the unofficial ГдеБЕНЗ API.

The information below is based on reverse engineering of the client application and observed server behavior.

Error Response Format

Most endpoints return JSON errors in the following format.

{
    "detail": "Error description"
}

Some endpoints may return an empty body.

HTTP Status Codes

Status Meaning
200 Request completed successfully
201 Resource created
204 No content
400 Invalid request
401 Unauthorized
403 Forbidden
404 Resource not found
405 Method not allowed
409 Conflict
413 Payload too large
415 Unsupported media type
422 Validation error
429 Too many requests
500 Internal server error
502 Bad gateway
503 Service unavailable
504 Gateway timeout

200 OK

The request completed successfully.

Example

HTTP/1.1 200 OK

Example body

{
    "vt":"2f8819c09b094bb48d4aa407",
    "ttl":1800
}

201 Created

Returned when a resource is successfully created.

Possible endpoints

POST /api/comments

POST /api/station-suggestions

204 No Content

Returned when no response body is required.

Not commonly observed.

400 Bad Request

The request is invalid.

Possible causes

  • Missing JSON body
  • Invalid parameters
  • Invalid coordinates
  • Malformed request
  • Invalid station ID

Example

{
    "detail":"Invalid request"
}

401 Unauthorized

Returned when an endpoint requires authorization and the caller is anonymous.

Observed on

POST /api/comments-onsite

Anonymous call with a valid body ({comment_id, osm_id, cvt}, osm_id as a string) returns:

{"detail":"Unauthorized"}

This endpoint additionally requires the visitor to be within 0.3 km of the station; a cvt whose osm does not match is rejected.

403 Forbidden

Returned when the server refuses to process the request.

Observed reasons

  • Voting outside Russia
  • Cloudflare validation failed
  • Invalid protection token
  • User banned
  • Feature disabled

Example

{
    "detail":"Forbidden"
}

Client message

Available only from Russia 🇷🇺

404 Not Found

Returned when the requested resource does not exist.

Examples

Station not found

Comment not found

Unknown endpoint

Example

{
    "detail":"Not Found"
}

405 Method Not Allowed

Occurs when using an unsupported HTTP method.

Example

GET /api/comments

when only POST is supported.

409 Conflict

One of the most common errors.

Returned when the request conflicts with current server state.

Observed examples

Duplicate vote

Vote cooldown

Duplicate station suggestion

Already pending

Already reported

Example

{
    "detail":"revote_cooldown"
}

The client displays

You can update this station every 4 hours.

Other possible response

{
    "detail":"already_exists"
}

413 Payload Too Large

Possible response when a submitted comment exceeds server limits.

Not directly observed.

415 Unsupported Media Type

Possible when JSON Content-Type is missing.

Example

Content-Type: text/plain

instead of

application/json

422 Validation Error

Possible validation response.

Typical causes

  • Missing fields
  • Invalid data types
  • Invalid coordinates

Example

{
    "detail":"Validation failed"
}

429 Too Many Requests

Observed frequently.

Returned when request rate exceeds server limits.

Examples

Voting too frequently

Too many reports

Too many suggestions

Repeated API requests

Example

{
    "detail":"Too many requests"
}

Client message

Too many requests — please try again later.

500 Internal Server Error

Unexpected server error.

Example

{
    "detail":"Internal server error"
}

502 Bad Gateway

Returned by reverse proxy.

Possible causes

  • Backend unavailable
  • Upstream timeout

503 Service Unavailable

Observed for disabled functionality.

Example

Station suggestions disabled

Client message

Station suggestions are currently unavailable.

Example

{
    "detail":"Service unavailable"
}

504 Gateway Timeout

Returned when the backend does not respond in time.

Not directly observed.

Vote Errors

Endpoint

POST /api/comments

Possible responses

Status Description
200 Vote accepted
400 Invalid request
403 Country restriction
409 Vote cooldown
429 Rate limit
500 Internal error

Report Errors

Endpoint

POST /api/comments/{id}/report

Possible responses

Status Description
200 Report accepted
400 Invalid request
403 Invalid RT token
409 Already reported
429 Too many reports

Suggestion Errors

Endpoint

POST /api/station-suggestions

Possible responses

Status Description
200 Suggestion accepted
400 Invalid map URL
403 User banned
409 Duplicate suggestion
429 Daily limit exceeded
503 Suggestions disabled

Search Errors

Endpoint

GET /api/search

Possible responses

Status Description
200 Success
400 Invalid query
429 Rate limit
500 Internal error

Nearby Errors

Endpoint

GET /api/nearby

Possible responses

Status Description
200 Success
400 Invalid coordinates
404 Area unavailable
429 Too many requests

Token Errors

Endpoint

GET /api/vt

Possible responses

Status Description
200 Success
500 Internal error

Endpoint

GET /api/rt

Possible responses

Status Description
200 Success
500 Internal error

Cloudflare Errors

Possible responses

Status Description
403 Turnstile verification failed
429 Bot protection triggered

Validation Errors

Common validation failures include

  • Missing station ID
  • Invalid latitude
  • Invalid longitude
  • Missing visitor token
  • Invalid report token
  • Missing JSON body
  • Invalid Content-Type

Client Error Handling

The client displays localized messages instead of raw server errors.

Examples

Server Client Message
403 Available only from Russia 🇷🇺
409 Vote cooldown
429 Too many requests
503 Service temporarily unavailable
Network Error Connection error

Retry Recommendations

Error Retry
400 No
403 No
404 No
409 Wait before retrying
429 Retry after delay
500 Retry later
502 Retry later
503 Retry later
504 Retry later

Observed Error Details

Known detail values observed during analysis include:

detail Meaning
revote_cooldown Vote cooldown period has not expired
already_exists Duplicate resource
forbidden Request denied
validation_failed Validation error
too_many_requests Rate limit exceeded
not_found Resource not found

Notes

Not every endpoint returns every status code listed above.

Some status codes are inferred from standard FastAPI/HTTP behavior, while others were directly observed during reverse engineering of the client application and network traffic.