Just as we have decided upon a small number of HTTPS status codes for REST, we have proposed the following types of errors to be used when we code.
Assertion failed
| Property |
Description |
| Friendly message |
An assertion made by the programmer proved to be wrong and the request couldn't be properly fulfilled. |
| Description |
Sometimes there are conditions that the programmer hasn't foreseen; assertion he or she had when the code was developed. This error is an indication that such an assertion proved wrong. This is a typical example of a "software bug". |
| Proposed action |
This is the kind of error that won't go away, unless a programmer finds the wrong assertion and does something about it. To help the programmer find the bug, the exception usually has a number of identifying codes connected to it. Please forward these to the programmer, it will help him/her to find the problem and to correct it. |
| Example |
The programmer did not think that someone would ever create a person with an empty field for "Given Name", so he/she did not prepare for this. As soon as someone actually does that, this kind of error would happen. |
| Type |
Xlent.Fulcrum.AssertionFailed |
| HTTP status code |
500 Internal Server Error |
Business rule
| Property |
Description |
| Friendly message |
The request conflicted with a business rules. Please make changes accordingly and try again. |
| Description |
The request was syntactically OK, but it did not fulfill one or more of the business rules. |
| Proposed action |
Try to correct your request and try again. |
| Example |
Suppose there is a business rule that the organization can't accept persons under the age of 13 as customers. A request that tries to create a new customer for a person that is 12, then this type of error would be triggered. |
| Type |
Xlent.Fulcrum.BusinessRule |
| HTTP status code |
400 Bad Request |
Conflict
| Property |
Description |
| Friendly message |
The request conflicted with a request by someone else. Please reload the information data and make a new request. |
| Description |
Sometimes there are more than one user making an update request for the same resource. If the two requests conflicts, the first request will succeed, but the second won't, because it is based on stale information. The party that receives this error needs to update their copy of the information, make the changes again and make a new update request. |
| Proposed action |
Make sure that you have the latest data and make a new request. |
| Example |
Two users are simultaneously changing the "Given Name" for the same person. After the first user has made a successful request of changing it, the second user now has stale information (the second user isn't aware of the update of the Given name) and needs to get the update before we can accept his/her update request. |
| Type |
Xlent.Fulcrum.Conflict |
| HTTP status code |
400 Bad Request |
Internal contract
| Property |
Description |
| Friendly message |
A programmer's code calls another part of the program in a bad way. (An end user is never supposed to see this error as it should be converted on the way.) |
| Description |
All methods in the code should have verification that the internal contract for the method (i.e. the requirements on the caller) are fulfilled. If not, this kind of error is triggered. Please note that this error means that there is an internal problem in the code, in contrast to theXLENT.Fulcrum.ServiceContract error which means that the caller of a service did not follow the contract. |
| Proposed action |
Report this error to the developers or maintainers of the code that reported the error. Be sure to attach all the information associated with this error. |
| Example |
Suppose that a part of the code requires an input parameter to always be greater than 0. When a programmer by error creates code that under some conditions sends in a negative value or zero to that function, this kind of error is triggered. |
| Type |
Xlent.Fulcrum.Contract |
| HTTP status code |
500 Internal Server Error |
Forbidden access
| Property |
Description |
| Friendly message |
The system could identify you, but you did not have right to access the resource. |
| Description |
Some resources are protected, so that they can only be read or altered by specific persons or systems. When someone else tries to access the resource, this error is triggered. |
| Proposed action |
Get the proper access rights and then try again. |
| Example |
Example: If the access rights for Person data has been set so that a person can only access his or her own data, then all persons will get this error when they try to access another persons data. |
| Type |
Xlent.Fulcrum.ForbiddenAccess |
| HTTP status code |
400 Bad Request |
Not found
| Property |
Description |
| Friendly message |
The resource with the given identification could not be found. Check that your information is correct or try again after a minute or so. |
| Description |
If your request is for a specific, identified resource and that resource can't be found, then this error is triggered. |
| Proposed action |
Either your identifier is incorrect, or you have information about an identifier that hasn't yet been created. In the latter case, you could very well try again after a minute or so, to give the system time to create the resource. |
| Example |
You get an identifier to a newly created person. You use that id to get information that is stored in another system. Due to latency, that system is not yet aware of the new person, so when you ask about the person, this kind of error is triggered. |
| Type |
Xlent.Fulcrum.NotFound |
| HTTP status code |
400 Bad Request |
Not implemented
| Property |
Description |
| Friendly message |
The request requires some functionality that deliberately has been left out, at least for the moment. |
| Description |
This is an error that shouldn't appear outside testing. If it does, then this means that a programmer has made a mistake; you have found a bug. |
| Proposed action |
Just like the AssertionFailedException, this is the kind of error that won't go away, unless a programmer does something about it. To help the programmer find the bug, the exception usually has a number of identifying codes connected to it. Please forward these to the programmer, it will help him/her to find the problem and to correct it. |
| Example |
The programmer didn't have time to finish the code, so he/she entered a marker in the code that the code isn't finished. When the code gets there, this kind of error is triggered. |
| Type |
Xlent.Fulcrum.NotImplemented |
| HTTP status code |
500 Internal Server Error |
Resource
| Property |
Description |
| Friendly message |
A resource used by the application had an internal error. |
| Description |
This is a way to blame a resource outside the application. |
| Proposed action |
Contact someone responsible for the resource and forward the information to them. |
| Example |
We call an external service by REST and the service a Xlent.Fulcrum.AssertionFailed. When forwarding the error up the our caller, we will transform it into a resource error to emphasize that the error was not in our application, but in another resource. |
| Type |
Xlent.Fulcrum.Resource |
| HTTP status code |
502 Bad Gateway |
Service contract
| Property |
Description |
| Friendly message |
The request contained data that was syntactically wrong, had values out of range, or something similar. |
| Description |
Whenever a request comes in, the input is checked so that it seems to be correct. If not, this kind of error is triggered. Compare this with the internal contract error that is for internal contracts. |
| Proposed action |
Correct the input and make a new request. |
| Example |
Suppose that you always have to enter a "Given Name" when you enter data about a person. If that field has been left blank, you will get this kind of error. |
| Type |
Xlent.Fulcrum.ServiceContract |
| HTTP status code |
400 Bad Request |
Try again
| Property |
Description |
| Friendly message |
A resource was temporarily locked or unavailable, please try again. |
| Description |
To handle simultaneous request for the same resource, the resource is sometimes locked. This means that any requests that come in during the lock is active will fail. |
| Proposed action |
Just try again. Normally you can try again within a couple of seconds, and your request will probably go through. |
| Example |
A database might have a limit of 100 simultaneous calls. If more calls are active, the calls will be rejected wíth this error. |
| Type |
Xlent.Fulcrum.TryAgain |
| HTTP status code |
500 Internal Server Error |
Unauthorized
| Property |
Description |
| Friendly message |
Authorization was missing or not accepted. |
| Description |
Most resources are protected from anonymous access. This means that a caller has to be authenticated (identified) to access the resource. If authentication is required and the call can not be authenticated, then this kind of error is triggered. |
| Proposed action |
Try again with proper authentication. |
| Example |
|
| Type |
Xlent.Fulcrum.Unauthorized |
| HTTP status code |
400 Bad Request |