The Grade.us API Version 4.0 is currently in Beta and is subject to change.

Error handling

The Grade.us API returns HTTP response status codes indicating the success or failure of your API requests. If your request fails, Grade.us returns an error with a relevant status code.

In general, there are three status code ranges you can expect:

  • 2xx success status codes confirm that your request worked as expected

  • 4xx error status codes indicate an error because of the information provided (e.g., a required parameter was omitted)

  • 5xx error status codes indicate an error with Grade.us’ servers

For 4xx errors, a custom error code will be provided, with explanations detailed below. Often, when receiving a 4xx error, a reference URL will be shown that provides an easy link to this documentation.

Error Codes


1000
unauthorized
(401)

Provided token does not exists. Unable to authorize!

1001
token_missing
(401)

Token missing. Please add it in 'Authorization' header.

1002
not_json_request
(406)

Only JSON requests allowed. Set 'Content-Type' header to 'application/json'

1003
not_found
(404)

Route not found

1004
bad_request
(400)

Something went wrong

1005
forbidden
(403)

Something went wrong

1006
unprocessable_entity
(422)

Something went wrong

1007
not_allowed_param
(422)

Not allowed params present: [list of not allowed params]. Allowed params are: [list of allowed params].

1008
missing_required_param
(422)

Following required params are missing: [list of missing params].

1009
not_allowed_value
(422)

Not allowed value '[VALUE]' present for '[Attribute]'. Allowed values are: [list of allowed values].

1010
disabled_api_access_error
(401)

Your API access must be enabled. Please contact Support.

1101
record_not_found
(404)

Record not found

1102
record_invalid
(422)

Invalid record

2000
user_limit_reached
(403)

User limit reached. Please purchase more seats.

2001
user_non_existent_profile
(404)

One or more profiles do not exist.

2002
user_invalid_subuser
(404)

Subuser does not exist.

2003
user_invalid_permissions
(400)

Invalid permissions.

2004
user_invalid_custom_permissions
(400)

Invalid custom permissions.

3000
brand_limit_reached
(403)

Brand limit reached. Upgrade to add additional brands.

3001
profile_limit_reached
(403)

Profile limit reached. Upgrade to add additional profiles.

3003
invalid_domain
(422)

Desired domain is not a valid domain name.

3004
domain_taken_by_user
(422)

Desired domain is already in use by another user.

3005
domain_taken_by_profile
(422)

Desired domain is already in use by another your profile.

3006
domain_taken_by_brand
(422)

Desired domain is already in use by another your brand.

3009
parent_profile_not_found
(404)

Parent profile with provided id not found.

3010
copy_not_parent
(404)

Profile with provided id is not a parent profile. When creating parent profile you can copy it only from other parent profile.

3011
profile_is_not_parent
(404)

Profile with provided id is not parent one. Please provide parent profile for creating child pages

3012
copy_not_found
(404)

Profile with provided id for copying not found.

3013
not_found
(404)

Profile with provided id not found.

3014
phone_text
(500)

Creating Phone/Text has failed. Please contact support.

3015
phone_area_code_not_supported_for_country
(422)

Phone area code not supported for provided country. Please remove area_code from parameters.

3016
unable_to_find_phone_number
(500)

Unable to find phone number. Please try again later or contact support.

3017
unable_to_find_phone_number_for_area_code
(422)

Unable to find phone number for area code provided area code. Please try different area code.

3018
phone_not_created
(400)

Profile ID does not have phone number created. Please create phone number first using 'create_phone' endpoint for profile ID

3019
email
(500)

Creating Email has failed. Please contact support.

3020
email_not_created
(400)

Profile ID does not have email created. Please create email first using 'create_email' endpoint for profile ID

3021
no_email_or_text_service
(400)

No email or text service is enabled for profile: ID.

3022
no_recipients_in_body
(400)

Please add one or more recipients. No recipient data was provided.

3023
recipients_upload_in_progress
(400)

Upload in progress, you must wait to add more recipients.

4001
invalid_url
(422)

Provided url is not valid.

4002
not_found
(404)

Link with provided id not found.

5001
not_found
(404)

Recipient with provided id not found.