Errors

The Routal API uses standard HTTP status codes. Every non-2xx response body is JSON with the same shape.

Error envelope

Every error response uses the same schema, named ApiError in the OpenAPI spec:

Example body:

{
  "message": "Domain not found",
  "message_id": "highway.domain.error.not_found"
}

• message is human-readable, suitable for log lines but not for end-user display. Wording can change for clarity across releases.
• message_id is the stable, dotted machine code. Use it for branching logic in your integration.

message_id follows the pattern highway.<context>.error.<reason>. highway is Routal's stable namespace for machine-readable error codes — branch on the full string, not on substrings.

HTTP status codes

Common machine codes

Routal emits dozens of message_id values across many domains. Below are the most common ones an integration tends to hit. Codes you don't see here exist — when in doubt, log the message_id you got back and contact support.

Authentication

There is no separate missing_key / invalid_key / revoked_key taxonomy — every API-key auth failure surfaces as highway.apiKey.error.not_found.

Resource not found

Validation

Some payload validation errors (missing required field, wrong type) surface as a plain 400 with a different body shape — no message_id, just a statusCode and a message describing the offending field:

{ "statusCode": 400, "error": "Bad Request", "message": "child \"label\" fails because [...]" }

Treat statusCode === 400 && !body.message_id as the sentinel for this case. Read message to figure out which field is wrong, fix the request, and don't retry until you've fixed it.

Permissions

Resource state

Optimization

Recovery patterns

Retry only on 429 and 5xx. Other 4xx codes will fail the same way on retry — fix the request first.

Use exponential backoff with jitter when retrying:

async function withRetry(fn, attempt = 0) {
  try {
    return await fn();
  } catch (err) {
    if (attempt >= 5 || !isRetryable(err)) throw err;
    const baseMs = 500 * 2 ** attempt;        // 500, 1000, 2000, 4000, 8000
    const jitterMs = Math.random() * 500;
    await new Promise((r) => setTimeout(r, baseMs + jitterMs));
    return withRetry(fn, attempt + 1);
  }
}

const isRetryable = (err) =>
  err.status === 429 || (err.status >= 500 && err.status < 600);

Log the message_id, not just the message. The message text may change for clarity; the message_id is stable across releases.

Reporting issues

If you hit a 5xx that persists, or a message_id you can't make sense of, email developers@routal.com and include:

• The endpoint (method + path)
• The full response body (message and message_id)
• An approximate timestamp (UTC)

That's enough to trace the request server-side.