Gateway error codes

What each code means when AgriGateway's gateway refuses or cannot complete a call, and what to do about it.

A gateway error has a JSON body with error.code, message, retryable and owner, and a correlation_id.

Every response carries X-Exchange-Correlation-Id and X-Exchange-Usage-Event-Id. Quote the correlation id when you ask for help.

A provider's own 4xx and 5xx responses pass through as the provider sent them, so they carry no code from this list. See the provider's documentation for those.

Your key

EX-AUTH-001

HTTP 401

The X-Exchange-Key is missing, malformed, unknown, revoked, expired or suspended, or its secret is wrong.

What to do: Send the whole key in the X-Exchange-Key header. If it is already there, check the key in API keys and make a new one if it has ended.

Who fixes it
You, the caller
Send it again?
No

EX-AUTH-002

HTTP 401

The key is valid, but for the other environment.

What to do: Call the service's sandbox host with a sandbox key and its live host with a live key.

Who fixes it
You, the caller
Send it again?
No

EX-AUTH-003

HTTP 401

A stream ticket is invalid, has expired, was already used, or is for another operation, environment or revision.

What to do: Ask for a new ticket from POST /_exchange/stream-tickets on the service's host. Each ticket works once, for one operation.

Who fixes it
You, the caller
Send it again?
No

Your access

EX-ACCESS-001

HTTP 403

This app has no active connection that covers this endpoint in this environment.

What to do: Check Connections. Request access to the service in this environment, or ask for this endpoint to be added to your connection.

Who fixes it
You, the caller
Send it again?
No

EX-ACCESS-002

HTTP 403

The endpoint is outside the connection.

What to do: Handle it as EX-ACCESS-001.

The gateway does not send this today: it answers EX-ACCESS-001 instead.

Who fixes it
You, the caller
Send it again?
No

EX-DATA-001

HTTP 403

The service holds restricted data, and calls to it are refused until its real-data governance gate is recorded.

What to do: Nothing in your call is wrong, and sending it again will not help until the gate is recorded.

Who fixes it
AgriGateway's data policy
Send it again?
No

The address you called

EX-ROUTE-001

HTTP 404

The gateway knows no service, endpoint or path at this address in this environment.

What to do: Check the host and path against the service's API reference. A service that is only in sandbox answers this on its live host, so use its sandbox host.

Who fixes it
You, the caller
Send it again?
No

EX-ROUTE-002

HTTP 405

This endpoint does not take this HTTP method.

What to do: Use the method shown in the service's API reference.

Who fixes it
You, the caller
Send it again?
No

Your request

EX-REQ-001

HTTP 400

The request is malformed, for example a repeated or invalid Content-Length, or a stream ticket request that is not a WebSocket handshake.

What to do: Fix the request before sending it again.

The contract also sets aside 422 with this code for a body that breaks the published schema. The gateway does not check that today.

Who fixes it
You, the caller
Send it again?
No

EX-REQ-002

HTTP 409

An Idempotency-Key was used again with a different body, or the request conflicts with the current state.

What to do: Use a new Idempotency-Key for a different body.

The gateway does not send this today. It is set aside for later connector work.

Who fixes it
Not stated
Send it again?
Not stated

Limits

EX-LIMIT-001

HTTP 429

Too many calls: over AgriGateway's rate for an endpoint, the plan's rate for your connection, or the number of requests allowed at once.

What to do: Wait for the seconds in the Retry-After header, at most 3,600, then send it again. A service's limits are on its Pricing and limits tab.

Who fixes it
You, the caller
Send it again?
Yes

EX-LIMIT-002

HTTP 429

The request quota for the day or month is used up.

What to do: Wait for the seconds in the Retry-After header. A service's quota is on its Pricing and limits tab.

Who fixes it
You, the caller
Send it again?
Yes

EX-LIMIT-003

HTTP 413

The request body is larger than this endpoint or connection allows.

What to do: Send a smaller body.

Who fixes it
You, the caller
Send it again?
No

The provider

EX-UPSTREAM-001

HTTP 504

The provider did not finish in time. The call may have reached it.

What to do: Check whether the call took effect before sending it again. If this keeps happening, tell the provider.

Who fixes it
The service's provider
Send it again?
No

EX-UPSTREAM-002

HTTP 502

The gateway could not get the credential it needs to call the provider, so the call was not forwarded.

What to do: Send it again shortly. If this keeps happening, contact AgriGateway with the correlation id.

Who fixes it
AgriGateway
Send it again?
Yes

EX-UPSTREAM-003

HTTP 503

No answer came from the provider: it is down, it is failing, or its address is outside what the gateway may call. A request that changes data may still have reached it.

What to do: If the request changes data, check whether it took effect first. Otherwise send it again after a wait. If this keeps happening, tell the provider.

Who fixes it
The service's provider
Send it again?
Yes

AgriGateway

EX-PLATFORM-001

HTTP 503

A part of AgriGateway the call depends on is unavailable, or the call could not be recorded for usage. The call was not forwarded.

What to do: Send it again after the Retry-After header, if there is one. If this keeps happening, contact AgriGateway with the correlation id.

Who fixes it
AgriGateway
Send it again?
Yes

Ids that are not errors

These look like error codes and appear in AgriGateway's documents, but they name requirements. The gateway never answers with them.

EX-FDR-001

The requirement on restricted data. A call refused under it is answered with EX-DATA-001.

EX-GWY-003

The requirement on the error format. Older documents used it for what is now EX-PLATFORM-001.

EX-MTR-001

The requirement that every attempt is recorded for usage. Its record is named in the X-Exchange-Usage-Event-Id header.

EX-SVC-011

The requirement on provider-native services: the provider's own paths and methods are kept, and others are refused.