Home/Getting started/Errors and Conventions ENУКРРУС API Reference (ReDoc) ↗

Errors and Conventions

Response shapes, what is stable, caching, limits.

Error shape

Every failure looks the same:

{
  "error": {
    "code": "language_not_found",
    "message": "Unknown language code: 'xx-YY'",
    "details": { "language": "xx-YY" }
  }
}

code is the contract — stable, snake_case, safe to branch on. message is for humans and may be reworded at any time. details carries the offending values and is present when there are any.

Full list: Error Codes.

Status codes

Status When
200 Success — including a batch where some items failed
404 language_not_found, provider_not_found
409 language_unsupported — both exist, the pair is refused
413 Request body over 256 KB
422 Malformed request (bad types, batch over 500 pairs)
503 Service not ready — database or catalog unavailable

Why 409 and not 404 for an unsupported pair

Both named resources exist; it is their combination that is refused. A caller retrying the same 404 forever would be drawing the wrong conclusion. In practice /v1/resolve reports this in the body as supported: false rather than raising, so you can log the pair and move on.

What is stable

Stable, and changed only with a new path version:

  • endpoint paths and query parameter names
  • field names in responses
  • error.code values
  • match values

Not stable — do not parse these:

  • message text
  • the order of aliases beyond "sorted"
  • the exact count of anything

New optional response fields may be added at any time. Ignore fields you do not know.

Caching

The catalog changes rarely — a few edits a month at most. Responses carry no Cache-Control yet, but the data is safe to cache on your side for minutes at a time. If you cache, cache the language and code pair, not the whole response.

Internally the service holds the catalog in memory and rebuilds it on a TTL and immediately after any admin write, so an edit in the panel is visible on the next request.

Limits

Limit Value
Request body 256 KB
Batch pairs 500 per request
Rate limit none — this is public read-only data

Correlation ids

Send X-Correlation-Id and it is echoed back and written into every log line for that request. Omit it and one is minted. Include it when reporting a problem.

Versioning

Paths carry /v1. A breaking change means /v2, served alongside /v1 for a deprecation window announced in advance.

Next