Error Handling

The Raisely API returns RFC7807 compliant errors. Don't worry if you don't know what that means, the important things to know are:

• HTTP status codes will be 4xx or 5xx when there's a problem
• The body of the response will be a JSON object
• The detail property of the JSON object can be shown to the end user
• The errors property contains an array giving specific details of one or more errors that occurred.

Raisely API supplies additional information in errors that can help you with debugging and handling errors automatically.

Example

Here's an example of a validation error that you might receive

{
	// A summary of the error that you can show to the user
	// When there is only one error this takes the value of errors[0].message
	"detail": "2 fields are invalid (profileUuid,userUuid)",
	// Identifies the kind of error
	"code": "invalid value",
	"type": "/errors/types/invalid-value",
	// Same as the HTTP status code of the response
	"status": 400,
	// You can pass this value to Support to help identify the 
	// specific instance of the error
	"instance": "/errors/occurrence/4fa30ffb-72ba-41cd-b90f-943ca2f30999",
	"time": "2020-11-02T10:18:35.242Z",
	"errors": [
		{
			"code": "invalid value",
			"message": "profileUuid is a required field",
			"status": 400,
			// Provides more detail on the nature of the error
			"subcode": "required",
			// Optional additional details about the object related to the error
			"field": "profileUuid",
			"recordType": "post",
			"detail": "One or more values is missing or invalid"
			"title": "Invalid value",
		},
		{
			"code": "invalid value",
			"message": "userUuid is a required field",
			"status": 400,
			"subcode": "required",
			"field": "userUuid",
			"recordType": "post",
			"title": "Invalid value",
			"detail": "One or more values is missing or invalid"
		}
	],
}

Errors and Subscodes

The error object will contain an errors property that is an array of one or more errors with additional detail. For example, if there is a validation error, you will receive an error with a code of invalid value and each of the entries in the errors array will correspond with an invalid field. Each entry will contain a subcode and other properties that describes the specific problem with that field.

Error Codes

The code value that is returned distinguishes the broad type of error(s) that occurred. Each will have a specific HTTP status code, but note that HTTP status codes do not correspond 1-to-1 with our error codes (for example invalid token and unauthorized are both 401 errors).

Authorization Errors

invalid token

The provided token cannot be used to access the API. It may have expired or been revoked.

unauthorized

This is returned when an attempt to become authorised fails, or when attempting to perform an operation that requires authorisation.

forbidden

The user is not permitted to access those resources. This could either be a permissions error because the user's role doesn't allow them to access those resources, or the resource may not be accessible to any users.

Record or Parameter Errors

Record or parameter errors represent problems with the state of the record, the operation you tried to perform or the fields you tried to access or change.

Any of these errors may include additional properties in the errors array to help you identify the cause of the error

not found

The record could not be found. This could be the record that you were looking for, or if you are creating a new record or filtering results, it could be a related record that you were trying to reference.

already exists

A record already exists and unique constraints prevent another from being created. For example, this might be thrown if you try to create a profile in a campaign with the same path as an existing profile in that campaign.

invalid record state

The current record state prevents you from performing the requested operation.

restricted field

You have attempted to access or change a field that you are not permitted. Some fields can only be set on creation, but not updated. While others can simply never be set or changed (eg uuid of a record)

invalid value

You have sent a parameter or field with an invalid value. The field and recordType properties should always be present to help you identify the problematic field. subcode is provided to help identify the specific problem.

Other Errors

payment gateway error

The payment gateway (eg Stripe or Paypal) returned an error.

rate limit exceeded

Some requests are limited in the frequency that they can be sent

payment required

The feature or service requires a paid plan to access. Not to be confused with errors from the payment gateway (above). This error is only returned when an admin tries to access a feature that requires a paid usage plan.

empty body

The body or (body.data) is missing from a POST, PATCH or PUT request

gone

The record no longer exists or the API path requested has been deprecated

internal error

An unexpected error has occurred with Raisely. If the error persists you can contact [email protected]