...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
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: |
...
|
...
|
...
|
...
|
...
|
...
HTTP Response Code: 404 | ||
PUT PATCH | HTTP Response Body: <<empty>> HTTP Response Code: 200 | HTTP Response Body: |
...
|
...
|
...
|
...
|
...
|
...
HTTP Response Code: 404 |