Web API Status Codes¶

The Domain Services Web API status codes are a subset of the standard HTTP status codes as defined by RFC2616.

The used status codes can be divided into the following 3 categories:

Code range	Category	Description
2xx	Successful	The client's request was successfully received, understood, and accepted.
4xx	Client Error	The client seems to have erred.
5xx	Server Error	The server has erred or is incapable of performing the request.

Successful¶

200 (OK)¶

Used when a successful query (GET or POST) or update (PUT) has been successfully processed by the server and a more specific code in the 2xx series is not applicable.

201 (Created)¶

Used when a POST request resulted in a new resource being successfully created on the server.

The response will contain a URI with a reference to the newly created resource in the Location header field. For example, creating a new user account called john.doe will result in a response with a location like this:

location: https://domainservices.dhigroup.com/api/accounts/john.doe

202 (Accepted)¶

Used when the request has been accepted for processing by the server, but the processing has not been completed. Examples of this could be canceling a running job execution or requesting a password reset.

204 (No Content)¶

Used when a resource is removed using a DELETE request. This indicates that the resource was successfully removed.

Client Error¶

400 (Bad Request)¶

This is a generic client-side error status, used when no other 4xx error code is applicable. This is typically caused by malformed request syntax or invalid request message parameters.

401 (Unauthorized)¶

This is used when the client tried to operate on a protected resource without providing the proper authorization. The response includes a WWW-Authenticate header field containing a challenge applicable to the requested resource. The below challenge signals that a bearer token (JWT) is expected.

www-authenticate: Bearer

403 (Forbidden)¶

Used when the client’s request is formed correctly, but the server refuses to honor it, because the requesting user does not have the necessary permissions for the resource.

404 (Not Found)¶

Used when the server can’t map the client’s URI to a resource - for example if the client requested a resource with an ID that does not exist. In this case, this will be clear from the response body that will contain an error message like the one below:

{
  "error": "'DHI.Services.Accounts.Account' with id 'john.doe' was not found."
}

406 (Not Acceptable)¶

Used when the server is not able to generate any of the client’s preferred media types, as indicated by the Accept request header. For example, a client request for data formatted as application/xml will receive a 406 status code if the server is only able to format data as application/json.

Server Error¶

500 (Internal Server Error)¶

This is the generic server error code. It is generated automatically by the ASP.NET Core framework whenever an unexpected error is thrown somewhere in the call stack and is not handled by the exception handling middleware.

501 (Not Implemented)¶

Used when the server lacks the ability to fulfill the request. This typically happens if a plugin has not implemented all of the interface members.

Exception Handling Middleware¶

Some of the error codes (4xx and 5xx) are automatically generated based on the type of .NET exceptions that was thrown in the call stack. This is done by some exception handling middleware (an IApplicationBuilder extension) exposed by the DHI.Services.WebApiCore component. This middleware can be added to the ASP.NET Core request pipeline in the Configure-method in startup.cs:

app.UseExceptionHandling();

This is already configured in the Domain Services Web API Visual Studio project templates.

The middleware converts the exception types to HTTP error codes using the following mapping:

.NET Exception	HTTP status code
KeyNotFoundException	404 (Not Found)
ArgumentOutOfRangeException	404 (Not Found)
ArgumentException	400 (Bad Request)
NotImplementedException	501 (Not Implemented)
NotSupportedException	501 (Not Implemented)
All other exceptions	500 (Internal Server Error)

There is an extended version of this middleware which will also log the exceptions to a logger of your choice:

app.UseExceptionHandlingWithLogging();