Instructions

Overview

The goal of the document is to describe error codes for API error handling.

Scope

Description of API HTTP status codes, error codes and messages.

HTTP Status Codes

API returns appropriate HTTP status code for every request.

HTTP Code	Text	Description
200	OK	Success
400	Bad Request	The request was invalid or cannot be otherwise served
401	Unauthorized	Missing or incorrect authentication credentials
403	Forbidden	The request is understood, but it has been refused or access is not allowed
404	Not Found	The requested resource does not exist
405	Method not allowed	The method received in the request-line is known by the origin server but not supported by the target resource
415	Unsupported Media Type	Request header is missing content-type (e.g. application/json)
500	Internal Server Error	Unspecified server error

Error Messages

API error messages are returned in JSON format, for example:

{"errors":[{"errorCode":3001, "message":"entity not found"}]}

In certain cases (e.g. in case of field validation error) additional attributes may be present in returned JSON:

{"errors":[{"errorCode":5000, "message":"validation error", "subject":"firstName", "subjectType":"parameter"}]}

Error Codes

In addition to descriptive error message, errors contain error codes. While the text for an error message may change, the codes will stay the same. If an error response is not listed in the table or missing, fall back to examining the HTTP status codes above.

Error Code	Message	Description
2006	entity saving error	Error occurred while saving the entity.
200601	entity saving error: USPTA number must be unique	Error occurred while saving the entity. USPTA number must be unique.
200602	entity saving error: PTR number must be unique	Error occurred while saving the entity. PTR number must be unique.
3001	entity not found	Entity was not found.
3002	entity already exists	Same entity already exists and cannot be created.
4003	authentication token is invalid	Authentication token is not valid.
4004	authentication error	Unknown authentication error occurred.
4005	backend system token is invalid	Authorization token for backend system call is not valid therefore request cannot be completed.
4006	access denied	Access is denied.
5000	validation error	Validation error. Additional attributes "subject" and "subjectType" may be present in response containing additional information (e.g. field name).
5001	illegal combination of method arguments	Supplied method arguments either invalid or incomplete.
5002	entity id is empty	Entity primary key is empty, request cannot be completed.
5003	unknown identifier error	Unknown entity identifier error.
5004	no remaining amount	No remaining amount error.
6001	empty client org	Empty "client org" attribute value.
6002	empty password	Password cannot be empty.
6003	invalid client grant type	Invalid "client grant type" value error.
6004	invalid client profile	Invalid "client profile" value error.
6005	invalid client scope set	Invalid "client scope" value error.
6006	new password not match	New passwords do not match.
6007	wrong password	Wrong password.
9001	unexpected system error	Unexpected system error.
9002	HTTP message not readable error	HTTP message not readable error.
9003	mail trigger error	Error while triggering an email.

API Responses

Unless otherwise specified, API HTTP responses will match the following:

Success (object exists)

Failure (object doesn't exist)

GET

HTTP Response Body: <<data in JSON format>>

HTTP Response Code: 200

HTTP Response Body:

{"errorCode": 3001, "message": "entity not found"}

HTTP Response Code: 404

PUT

PATCH

HTTP Response Body: <<empty>>

HTTP Response Code: 200