Errors

agrirouter has two API surfaces with very different error conventions. The current API returns plain human-readable JSON messages. The legacy API returns numeric codes inside a protobuf envelope. This page covers both.

Every error response on the current API has the same shape:

{
  "message": "A human-readable description of the error."
}

There is no numeric code field on the wire. Branch on the HTTP status code; the message string carries the human-readable detail. Values like message IDs or endpoint IDs are already substituted into the text, so you can log it directly or wrap it in your own UI copy.

HTTP status codes

The current API uses the following status codes across its endpoints. Individual endpoint pages list which statuses apply to that endpoint.

Rate limits

Request limits are enforced per application across all its endpoints. When the limit is exceeded, the gateway responds with HTTP 429 and a plain { "message": "rate limit exceeded" } body. The response does not include a Retry-After header, so client code should fall back to its own exponential backoff.

Concrete limits vary by environment and application tier and may change over time. For the current limit for your application, write to support@agrirouter.com.

Relationship to the legacy codes

Internally, agrirouter still runs the same validation logic that produces the legacy VAL_000XXX and SYS_000XXX codes listed below. On the current API, the numeric code is stripped before the response goes out, and only the human-readable message reaches the wire. That means:

• You cannot distinguish VAL_000004 ("all routes failed") from VAL_000005 ("some routes failed") from the status line alone. Both surface as HTTP 400 with a plain { "message": "..." } body.
• Your code should rely on the HTTP status and, where disambiguation matters, on pattern-matching the message string. It should not attempt to parse numeric codes out of the JSON body.

Legacy API error codes

Message placeholders

Legacy error messages may contain the following placeholders, which agrirouter replaces with actual values at runtime:

Error categories

Troubleshooting legacy responses

• SYS errors: server-side. Retry with exponential backoff. If they persist, check the status page.
• VAL_000001–VAL_000003: double-check your message encoding and header fields.
• VAL_000004 and VAL_000005: review your route configuration in the agrirouter UI. On the current API, both complete and partial routing failures surface as HTTP 400 with a plain message body, so the numeric distinction is only visible on the legacy wire.
• VAL_000201–VAL_000209: check your legacy onboarding flow. TANs must be fresh and application IDs correct.
• VAL_000303: typically means you are trying to use a VCU capability on an endpoint that is not a telemetry platform endpoint.

Next steps