Open Bug 529569 Opened 15 years ago Updated 14 years ago

WebService API error code documentation issues

Categories

(Bugzilla :: WebService, defect)

defect
Not set
normal

Tracking

()

People

(Reporter: gerv, Unassigned)

Details

I think the WebService API error codes are excellent, and I want to use them on the HTTP API also. However, in studying them in order to implement them (and collating them: https://wiki.mozilla.org/Bugzilla:WebServices:Errors ), I've come across the following issues. They are all in one bug for my convenience :-) but if you want them split out, please say so.

1. Documentation error - Bug.add_comment and Bug.update are documented as returning code 108 for "edit denied". However, Constants.pm suggests that this should be 109 (108 is "invalid_field_name").

It is sometimes not clear what a particular error code is meant to mean, because it is thrown by several methods and the documentation for each of those methods only says what it means in that context. So it's not always possible to work out the "unifying theme".

2. Bug.create uses code 51 for "invalid object", whereas User.get uses code 51 for "invalid login name". What is the unifying theme for code 51? "Bad parameter value"?

Conversely, sometimes there are two error codes for seemingly the same thing.

3. What is the difference between code 100 (Invalid Bug Alias), as thrown by Bug.get and Bug.add_comment and code 103 (Invalid Alias) as thrown by Bug.create?

4. Same question for 51 (Invalid Object) and 104 (Invalid Field).

5. Which is Invalid User a 500-series error (504) whereas the other Invalid Field errors are 100-series errors?

I hope this is useful feedback :-)

Gerv
A couple more:

4a. What's the difference between 53 param_invalid, 51 Invalid Object, 52 param_must_be_numeric/xmlrpc_invalid_value, and 104?

6. What's the difference between 300 (Invalid Username or Password) and 302 auth_invalid_email?

Gerv
Well, the logic of the error codes is restricted by how Bugzilla's exception system works, pretty much.

For anything more advanced than XML-RPC, I'd suggest also sending along the error name and all the arguments that were passed to the error (though in case of objects you might have to be careful for security reasons). Of course, I suppose you don't have the power to do that in your API, but we have the power to do it in the JSON-RPC case (and so we should do it, probably before 3.6 is released).

I'll address your questions in a separate comment.
(In reply to comment #0)
> 1. Documentation error - Bug.add_comment and Bug.update are documented as
> returning code 108 for "edit denied". However, Constants.pm suggests that this
> should be 109 (108 is "invalid_field_name").

  Okay. Could you add a patch for that (probably back to 3.2 I'd guess). Also, there is no Bug.update--I'm assuming you mean Bug.update_see_also?

> 2. Bug.create uses code 51 for "invalid object", whereas User.get uses code 51
> for "invalid login name". What is the unifying theme for code 51? "Bad
> parameter value"?

  Error codes can't really be accurately documented separate from the method that they are being called on. However, if you look at WebServices::Constants, 51 is mostly object_not_found, which simply means "you specified some value that does not exist in the database."

> 3. What is the difference between code 100 (Invalid Bug Alias), as thrown by
> Bug.get and Bug.add_comment and code 103 (Invalid Alias) as thrown by
> Bug.create?

  100 means "there is no bug with that alias", I believe, and 103 means "you specified a string that cannot be used as an alias when creating bugs".

> 4. Same question for 51 (Invalid Object) and 104 (Invalid Field).

  Legacy. 104 is thrown by old code (and is specific to fields), 51 is thrown by new code (and applies to all objects in the database).

> 5. Which is Invalid User a 500-series error (504) whereas the other Invalid
> Field errors are 100-series errors?

  User errors are supposed to all be in the 500 range, and I think that that error code was originally added as part of User.get or something like that.

(In reply to comment #1)
> 4a. What's the difference between 53 param_invalid, 51 Invalid Object, 52
> param_must_be_numeric/xmlrpc_invalid_value, and 104?

  param_invalid means that you attempted to pass an undefined value to an internal function in Bugzilla.

  51 is explained above.

  52 means that your XML-RPC input is actually itself invalid--you specified something like <int>a string</int>, or you tried to pass a string into a parameter that only accepts ints.

> 6. What's the difference between 300 (Invalid Username or Password) and 302
> auth_invalid_email?

  Generally these can be answered by grepping the code for the error identifier, but I understand where this one might be hard to decipher.

  auth_invalid_email is thrown in the case where an external verification source returns an email address that is not valid, such as LDAP.
Thanks - that explains a lot. A few follow-up questions:

> Error codes can't really be accurately documented separate from the method
> that they are being called on.

My understanding was that the error codes would have a fairly well-defined meaning independent of the method which you called. (And if there were new meanings to be added, then new codes would be made, rather than re-using existing ones). And this does seem to be the practice most of the time - hence my question about code 51.

If code 51 is "invalid object", isn't that a bit generic for the client to be able to give the user a useful error message? We seem to have different codes for "invalid <foo-field>" for several values of foo-field; presumably using those is preferred?

Is param_invalid then a Bugzilla coding error?

Lastly, if I need new error codes for the HTTP API, is that OK with you? Would it be reasonable to use the wiki page I created (now updated with the info you just gave above) as a registry of error codes?
https://wiki.mozilla.org/Bugzilla:WebServices:Errors
It would be great if you could provide a short summary of the logic behind which sort of error goes in which numerical range.

Bug 531257 filed on the documentation issue.

Gerv
(In reply to comment #4)
> If code 51 is "invalid object", isn't that a bit generic for the client to be
> able to give the user a useful error message?

  It is. Unfortunately XML-RPC doesn't allow me to modify the error format, so I can't include information that would make it more useful. JSON-RPC allows us to add additional error data, so we probably will do that. (For example, if we included the arguments that the error got, and then also the string id of the error, that would probably be enough.)

> We seem to have different codes
> for "invalid <foo-field>" for several values of foo-field; presumably using
> those is preferred?

  No, because we want to centralize architecture in Bugzilla::Object. The field-specific error messages are mostly a legacy thing.

> Is param_invalid then a Bugzilla coding error?

  It's a CodeError in Bugzilla because under normal circumstances (outside of the API) a user can't make it happen. However, in the API, it can happen, so we return it with a positive error code instead of a negative error code.

> Lastly, if I need new error codes for the HTTP API, is that OK with you? Would
> it be reasonable to use the wiki page I created (now updated with the info you
> just gave above) as a registry of error codes?

  I'm uneasy with blessing error codes that aren't actually directly in the Bugzilla codebase. Perhaps some sort of mechanism to note that your error codes are custom, like adding a certain number to them, would allow future compatibility without sacrificing your flexibility.

> It would be great if you could provide a short summary of the logic behind
> which sort of error goes in which numerical range.

  Mostly it sort of goes by what module you expect to throw the error, or what the error is related to. When it could be multiple modules or areas of code, it's sort of a judgment call.
You need to log in before you can comment on or make changes to this bug.