A request fails with GatewayRequestException
Environment
Every version of the client against the data service Wkl.Data.Gateway.
Cause
Every source of error—a response from the service, a timeout, a broken connection, an unreadable
response—arrives as GatewayRequestException with a GatewayProblem: Kind (the kind), Message
(text from the service or the client), CorrelationId (the ID under which the service logs the
details), and IsTransient (true only for Unavailable and TimedOut).
The service names a code in its response, and the client takes its kind from it. If there's no code
(for example, because a proxy or load balancer answered instead of the service), the client classifies
by HTTP status: 400 → MalformedRequest, 401 → Unauthenticated, 403 → Forbidden, 404 →
UnknownResource, 409 → Conflict, 412 → PreconditionFailed, 413, 414, and 429 →
LimitExceeded, 422 → DatabaseRejected, 504 → TimedOut, any other status → Unavailable. The
service reports its own errors with these codes; a 500 comes from a component between the client
and the service, or from an unexpected error that the service couldn't catch.
Two errors don't arrive as GatewayRequestException:
ArgumentExceptionwhen you create aGatewayResource,GatewayQuery,GatewayFilter, orGatewayRoutineRequest, and fromReadAsyncfor an argument name: a name isn't a valid identifier, or a value is out of range (see API reference). No request was sent.JsonExceptionwhile the rows are read: the response doesn't fitTRow, for example because a column returns text and the property expects a number. The request did run; correct the row type or read intoJsonElement.
Resolution
Kind | Meaning | What to do |
|---|---|---|
Unauthenticated | no key set; the key is invalid, revoked, or expired; or a sign-in rule requires a second factor | Check the environment variable named in ApiKeyEnvironmentVariable (it's read for each request; if it's missing, no request is sent). If a rule requires a second factor, the client can't use the key; ask the service's administrator for a key without that requirement |
Forbidden | the key's rule doesn't allow the access | Have the service's administrator check the rule; include the CorrelationId |
UnknownResource | the alias or object doesn't exist or isn't approved—deliberately indistinguishable. An unknown field arrives as MalformedRequest instead | Check the spelling; then proceed as for Forbidden |
UnknownResource only for long read requests | an older service doesn't accept read requests in the body (POST …/$query) | Increase MaxUrlLength or update the service |
MalformedRequest | the request is invalid, for example an unknown field, a value of a type that can't be transmitted, or arguments for an object that takes none | Check field names, filters, and values |
LimitExceeded | too many requests (429), the request is too large (413, 414), or the response is larger than MaxResponseBytes and the service stated its length in advance | For 429, try again later; otherwise reduce the window or the field selection, or increase MaxResponseBytes |
DatabaseRejected | the database or the procedure rejected the request | If the procedure raised a message (THROW or RAISERROR with a number of 50000 or higher and severity 11 to 16), Message contains its text; otherwise Message is a fixed text, and EngineMessages gives the reason (see below) |
Conflict | the statement violates a key or unique index, also inside a procedure (client 0.2.1 and later) | Don't retry: the same request fails again. Check the values; EngineMessages names the message |
PreconditionFailed | the row was changed after it was read (client 0.2.1 and later) | Read it again and repeat the change on the new state |
TimedOut | the service canceled the statement after its time limit | Reading: narrow the request or try again later. Calling: don't retry blindly—first check whether the procedure took effect |
Unavailable | the service or the database can't be reached, the connection broke, the response is unreadable, or the client gave up after its own time limit | Reading: try again later; if it persists, contact the administrator. Calling: don't retry blindly—if the request was sent, the procedure may have taken effect |
DatabaseUnreadable | SQL Server responds but can't read the alias's database (client 0.2.0 and later) | Don't retry (IsTransient is false): it stays this way until the operator fixes the cause, usually by restarting SQL Server; contact the administrator with the CorrelationId |
IsTransient only says whether the same request could succeed later. It doesn't say whether a
retry is harmless: for a procedure call, the application decides that.
For any question to the administrator, include the CorrelationId, the time, the alias, and the
object.
DatabaseUnreadable doesn't cover every unreadable database. The service reports DatabaseUnreadable only
for a fixed list of SQL Server error numbers; a read error for any other reason still arrives as
Unavailable. So the absence of this kind doesn't prove that the database is readable. The list is in
“HTTP: native API (reference)” (data service documentation), section “Error format.”
SQL Server messages (client 0.2.0 and later). Problem.EngineMessages contains Number,
SqlState, Severity, Message, and Released for each message. If Released is false, Message
holds a text from the service instead of SQL Server's text, because SQL Server's text would name objects
the caller isn't allowed to see or—under the alias's login—could quote a data value; the number
and SQLSTATE always arrive. A service before contract 0.5.0 sends no messages; the list is then empty.
For a broken connection and a timeout, it's always empty.