Errors

ReferralHero uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, an update failed, etc.), and codes in the 5xx range indicate an error with ReferralHero's servers (these are rare).

When a request returns an error we always try to provide a clear explanation of what went wrong. Errors are returned as JSON files and follow the same structure:

{
  status: "error",
  message: "Error explanation" // Eg: "Missing API token"
  code: "error_code" // Eg: no_token
}

Status

Our API raises errors for many reasons and when this happens the "status" attribute will always be "error". We recommend writing code that gracefully handles all possible API exceptions.

Message

A human-readable message providing more details about the error.

Code

The type of error returned. See list of possible errors below:

Error codes	Explanation
no_token	"api_token" parameter is missing or blank
invalid_token	"api_token" provided does not exist
inactive_account	Account associated with this API token is inactive
too_many_calls	Rate limit hit. Wait 60 minutes to reset the counter.
no_list_uuid	"uuid" parameter is missing or blank
invalid_list	"uuid" provided belongs is invalid
no_subscriber_id	"subscriber_id" parameter is missing or blank
subscriber_not_found	subscriber provided does not exist
no_email_address	"email" parameter is missing or blank
invalid_email_address	"email" provided is not a valid email.
no_name	"name" parameter is missing or blank
no_points	"points" parameter is missing or blankno_hosting_url
no_hosting_url	"hosting_url" parameter is missing or blank
error_list_creation	Something went wrong when creating a new list.
subscriber_already_promoted	Subscriber's already been promoted
subscriber_not_promoted	Subscriber is not promoted, hence it can't be "unpromoted"
bad_request	Missing required params
reward_not_found	The provided reward does not exist
invalid_status	The provided 'status' does not exist
no_coupons	The "coupons" parameter is missing or blank
error_coupon_group_creation	Errors occured while creating coupon
coupon_group_created	Coupon created successfully