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
409	Conflict	The request cannot be completed because of the conflict
415	Unsupported Media Type	Request header is missing content-type (e.g. application/json)
429	Too Many Requests	The response indicates the user has sent too many requests in a given amount of time
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.
200603	entity saving error: member with active or lapsed status cannot modify firstName, lastName, dateOfBirth, gender	Error occurred while saving the entity. Member with active or lapsed status cannot modify firstName, lastName, dateOfBirth, gender.
3001	entity not found	Entity was not found. The response will have "404 Not Found" HTTP status code.
3002	entity already exists	Same entity already exists and cannot be created. The response will have "409 Conflict" HTTP status code.
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.
400601	access denied: address can only be changed by the head of household	Access is denied. Only head of household can change the address.
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.
5101	schoolType attribute is not supported for that type of organization	SchoolType attribute is only supported for organizations with orgType equal to "School"
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.
9004	mail status retrieval error	Error when getting status of an email.
9005	mail input param is invalid	Error when Client provided the mailing service with incorrect arguments.

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