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, so a change to the catalog becomes visible without a restart.

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