Bugzilla::WebService - The Web Service interface to Bugzilla
This is the standard API for external programs that want to interact with Bugzilla. It provides various methods in various modules.
Methods are marked STABLE if you can expect their parameters and return values not to change between versions of Bugzilla. You are best off always using methods marked STABLE. We may add parameters and additional items to the return values, but your old code will always continue to work with any new changes we make. If we ever break a STABLE interface, we'll post a big notice in the Release Notes, and it will only happen during a major new release.
Methods (or parts of methods) are marked EXPERIMENTAL if we believe they will be stable, but there's a slight chance that small parts will change in the future.
Certain parts of a method's description may be marked as UNSTABLE, in which case those parts are not guaranteed to stay the same between Bugzilla versions.
If a particular webservice call fails, it will throw a standard XML-RPC error. There will be a numeric error code, and then the description field will contain descriptive text of the error. Each error that Bugzilla can throw has a specific code that will not change between versions of Bugzilla.
The various errors that functions can throw are specified by the documentation of those functions.
If your code needs to know what error Bugzilla threw, use the numeric code. Don't try to parse the description, because that may change from version to version of Bugzilla.
Note that if you display the error to the user in an HTML program, make sure that you properly escape the error, as it will not be HTML-escaped.
If the error code is a number greater than 0, the error is considered "transient," which means that it was an error made by the user, not some problem with Bugzilla itself.
If the error code is a number less than 0, the error is "fatal," which means that it's some error in Bugzilla itself that probably requires administrative attention.
Negative numbers and positive numbers don't overlap. That is, if there's an error 302, there won't be an error -302.
Sometimes a function will throw an error that doesn't have a specific error code.
In this case,
the code will be -32000 if it's a "fatal" error,
and 32000 if it's a "transient" error.