Dereference error type field in REST API documentation #5558

New issue

Open

opened 2026-02-22 11:43:27 -05:00 by deekerman · 1 comment

deekerman commented

2026-02-22 11:43:27 -05:00

Owner

Originally created by @Schoumi on GitHub (May 28, 2024).

Describe the current behavior

The documentation says that code and error in JSON errors are now deprectated and replaced by type and details.
I'm not sure why you come to change type to an URL that leads nowhere (no documentation in the end) who is less clearer and parsable than code.

{
"type":"https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/missing_two_factor",
"detail":"Missing two factor header",
"status":401,
"docs":"https://docs.joinpeertube.org/api-rest-reference.html#operation/getOAuthToken",
"code":"missing_two_factor",
"error":"Missing two factor header"
}

Steps to reproduce

No response

Describe the expected behavior

It's easier for client apps to make some treatment based on code than type now. if you really want to go to URI something like: "error://peertube/auth/missing_two_factor" will be better than we have now. We get that the error is from peertube, about auth.
If you don't go to separate error code in sub sections i'm not sure the type improve anything.

Additional information

No response

Originally created by @Schoumi on GitHub (May 28, 2024). ### Describe the current behavior The documentation says that code and error in JSON errors are now deprectated and replaced by type and details. I'm not sure why you come to change type to an URL that leads nowhere (no documentation in the end) who is less clearer and parsable than code. ```json { "type":"https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/missing_two_factor", "detail":"Missing two factor header", "status":401, "docs":"https://docs.joinpeertube.org/api-rest-reference.html#operation/getOAuthToken", "code":"missing_two_factor", "error":"Missing two factor header" } ``` ### Steps to reproduce _No response_ ### Describe the expected behavior It's easier for client apps to make some treatment based on code than type now. if you really want to go to URI something like: "error://peertube/auth/missing_two_factor" will be better than we have now. We get that the error is from peertube, about auth. If you don't go to separate error code in sub sections i'm not sure the type improve anything. ### Additional information _No response_

deekerman added the

Type: Feature Request ✨

Component: Documentation 📚

labels

2026-02-22 11:43:27 -05:00

deekerman commented

2026-02-22 11:43:33 -05:00

Author

Owner

@Chocobozzz commented on GitHub (May 29, 2024):

Hi,

We try to follow https://datatracker.ietf.org/doc/html/rfc7807#section-3.1, it's the reason why it's an URI.

But it would be better to update the documentation so the type can be correctly dereferenced.

We'll keep code field as I agree it's easier to parse (github.com/Chocobozzz/PeerTube@da7ccbb44a)

@Chocobozzz commented on GitHub (May 29, 2024): Hi, We try to follow https://datatracker.ietf.org/doc/html/rfc7807#section-3.1, it's the reason why it's an URI. But it would be better to update the documentation so the `type` can be correctly dereferenced. We'll keep `code` field as I agree it's easier to parse (https://github.com/Chocobozzz/PeerTube/commit/da7ccbb44a469633af987a584392b87f8a01d26e)