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	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.

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