Error Handling

In case of an error, the Gateway returns appropriate HTTP status code and error body. Embedded Chain uses HTTP status codes to indicate the success or failure of an API request.

• "2xx": indicates success
• "4xx": indicates developer or client application related errors
• "5xx": indicates Embedded Gateway related errors

Error Schema

NAME	TYPE	DESCRIPTION
status_code	integer	Standard HTTP status code of response
error_type	string	Identifies the broad category of error that occurred. For programmatic use.
error_sub_type	string	Describes the error in more detail For programmatic use. Optional.
message	string	A message explaining the error. Meant for the developer.

Error Types

Common Errors (any Request)

STATUS CODE	ERROR TYPE	ERROR SUB TYPE	DESCRIPTION
400	"invalid_token"		The authorization token is missing or invalid
401	"unauthorized_token"		The authorization token is not authentic
500	"server_error"		Embedded Gateway encountered an unexpected error.

Operation-specific Errors

STATUS CODE	ERROR TYPE	ERROR SUB TYPE	DESCRIPTION
504	"not_found_error"	"shipment_not_found"	Shipment could not be found on the remote server.

Endpoint	Status Code	Error Type	Error Subtype	Message
/connection/setup/validate	400	validation_error	invalid_client_id scope_missing invalid_scope invalid_redirect_url	If 'invalid_scope' is returned, will include a list of the invalid scopes.
/ connection/token/exchange	401	authentication_error	client_authentication_error	Client could not be authenticated using client_id and client_secret.',
/ connection/token/exchange	400	invalid_token	exchange_token_expired	Exchange token has expired.
/ connection/token/exchange	400	invalid_token	exchange_token_not_found	Exchange token could not be found.
/ connection/token/exchange	400	invalid_token	exchange_token_environment_mismatch	Exchange token was created in a different environment. Expected 'production', token was created in 'sandbox',
/ connection/token/exchange	400	invalid_token	exchange_token_reused	Exchange token has already been exchanged for a connection token
/get-shipment (Not complete)	404	not_found_error	shipment_not_found	Could not find shipment with id S109 on remote server'
/get-shipment (Not complete)	403	authorization_error	unauthorized_scope	Connection is not authorized for this scope: SHIPMENT_READ'
/get-shipment (Not complete)	403	authorization_error	incorrect_environment	connection is not valid for the environment: sandbox, it was created for production',
	503	remote_service_unavailable
	511	invalid_credentials
	504	remote_service_timeout