Problem responses

This page lists all explicitly supported exceptions and some guidance on how to handle them. In exceptional cases, an exception in the applications will not be handled by specialized exception handlers but instead delegate to the default exception handling. These responses are not described here but should still provide insights into potential ways of handling them.

See Resilience for guidance on generic exception handling.

Not Allowed

This response indicates that the client used an unsupported request method (aka HTTP Verb).

Not Acceptable

This response indicates that the server can not provide a response matching the client's requested response type as specified in the Accept header.

Unsupported Content Type

This response indicates that the server can not process the request's content due to unsupported formatting. This error can have several causes, either

• the request body itself, or
• the media type of the request, or
• in rare cases the content encoding of the request.

Not Found

This response indicates that one or more of the entities required to fulfil the request could not be found. This can be both due to the business_id not being found, or the specified version (defined in the If-Match-header using a weak ETag) not being available.

There are several reasons why this might occur. In the case of an entity not being found, there might be a race condition in the integration (another thread has already removed the entity in question) or invalid state in the integration (the integration does not know whether the entity already exists or has been deleted). A Not Found due to the version not matching usually points to a race condition.

Conflict

This response indicates concurrent conflicting write operations have occurred during the processing of the request. Write operations happen within a transaction to ensure ACID operations, when two writes impact the same entities only one of them is acknowledged.

Invalid Format

This response indicated an error in the request's body. The message could not be correctly converted to the internal representation of this request. The response can provide additional details on the errors, in the violations-field, depending on how severe they are. Eg: An unparsable JSON will not contain additional details, while an invalid JSON will try to point to the invalid fields.

Business Constraint

This response indicates that the request violates one or more business rules. The response will explain the broken constraints in the detail property or specify individual constraint violations per field in the violations property.

Constraint Violation

This response indicates an optimistic lock failure. When providing an If-Match-header, containing a weak ETag representing the entity version, this lock is validating before modifying the entity in question.

Payload too large

This response indicates that the body of the request is too large. Some endpoints might limit the amount of data you can send.

Unauthorized

This response indicates that the request is missing valid authentication credentials. Either no valid token was provided or the token has expired. See authentication for more details.

Forbidden

This response indicates that the token is not allowed to perform the action. When you get this error it means that you are authenticated successfully, but the current user or service account is not allowed to perform the action.

Gateway Timeout

This response indicates a timeout when executing calls to downstream systems.

Service Unavailable

This response indicates a required service for handling the request is unavailable. There are several potential causes for this response:

• A component upstream from the application is unresponsive. See Resilience on general strategies for handling these resonses, or
• A downstream component is unresponsive. The application should provide guidance in the error response.

Server Error

This response indicates an unrecoverable exception has occurred while processing your request. This could be either due to an internal issue or errors in downstream systems.