Add doc on error handling #19
Conversation
i2y
force-pushed
the
docs/error-handling
branch
2 times, most recently
from
6136ab2 to
21f3980
Compare
Signed-off-by: i2y <6240399+i2y@users.noreply.github.com>
i2y
force-pushed
the
docs/error-handling
branch
from
9b73ddf to
a7bd90b
Compare
docs/errors.md
Outdated
| ```json | ||
| HTTP/1.1 400 Bad Request | ||
| Content-Type: application/json | ||
|
|
||
| { | ||
| "code": "invalid_argument", | ||
| "message": "name is required", | ||
| "details": [ | ||
| { | ||
| "type": "google.protobuf.Struct", | ||
| "value": "base64-encoded-protobuf" | ||
| } | ||
| ] | ||
| } | ||
| ``` |
There was a problem hiding this comment.
nit: not sure if http is a valid markdown language tag, but could be more appropriate here if it is. (although then maybe the json wouldn't be pretty 😞.)
can probably just ignore this.
There was a problem hiding this comment.
Thanks! I changed json to http now
| Select error codes that accurately reflect the situation: | ||
|
|
||
| - Use `INVALID_ARGUMENT` for malformed requests that should never be retried | ||
| - Use `FAILED_PRECONDITION` for requests that might succeed if the system state changes | ||
| - Use `UNAVAILABLE` for transient failures that should be retried | ||
| - Use `INTERNAL` sparingly - it indicates a bug in your code |
There was a problem hiding this comment.
I might link to https://connectrpc.com/docs/protocol#error-codes; the discussion below the table about how to choose an error code is pretty useful.
There was a problem hiding this comment.
I see, thanks! I just wrote the link below.
| violation = bad_request.field_violations.add() | ||
| violation.field = field | ||
| violation.description = error | ||
| raise ConnectError(Code.INVALID_ARGUMENT, "Validation failed", details=[bad_request]) |
There was a problem hiding this comment.
my only hesitation on recommending error details is that in practice, they can make it more difficult to debug if your client isn't already deserializing them. And there's no way to strongly enforce them in your API contract; the best you can really do is just document them.
I think this is fine to leave as-is, just wish error details were easier to use in general.
There was a problem hiding this comment.
I think this PR is trying to match the coverage of Go docs which similarly cover error details so is probably good as is. Agree that error details are a bit clunky but too useful for substituting for custom error codes to leave out.
There was a problem hiding this comment.
I see. I agree with both opinions, so I just added this https://github.com/connectrpc/connect-python/pull/19/files#diff-72376d0b487d7231cf31959bf266f6aea098e899743bae02e36d176cef4db476R210
Signed-off-by: i2y <6240399+i2y@users.noreply.github.com>
3 participants
This PR adds error handling documentation covering error codes, client/server examples, error details, and best practices.