Errors

The Sell API 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 indicate an error with the provided information (errors with the information provided), and codes in the 5xx range indicate a server-side error.

Header

An error response should specify the Content-Language of the response and have Content-Type set to the application/json; charset=utf-8 value.

---

Body

The general format of an error's envelope includes two fields: errors and meta. They are described below in a separate subsection.

This is the basic structure of the error response:

{
  "errors":[{
    "error": {
      "resource": "resource name",
      "field": "field name",
      "code": "error_code",
      "message": "End user human readable description",
      "details": "Detailed description"
    },
    "meta": {
      "type": "error",
      "links": {
        "more_info": "$link_to_error_related_doc"
      }
    }
  }],
  "meta": {
    "type": "errors",
    "http_status": "http_status_code http_status_message",
    "logref": "$Headers[X-Request-Id]",
    "links": {
      "more_info": "$link_to_helpful_resource"
    }
  }
}

---

Errors Attributes

The errors attribute is a JSON collection of objects that holds error information and related metadata, such as links to related documentation. Each error object can hold additional metadata in the meta object.

Error object represent either an invalid request error or a resource error.

The error fields are described below:

Name	Description
code	The error code.
message	Human readable error description in a language specified by the Content-Language header.
details	An optional detailed descriptive text targeted at the client developer in English.
resource	An optional resource name the error relates to. Present only if the error represents a resource error.
field	An optional field name of the resource the error relates to, in the JSON Pointer format. Present only if the error represents a resource error.

Meta Attributes

Name	Description
http_status	HTTP status code of the response plus HTTP response status message.
logref	Unique id of the request. This is the same value as the X-Request-Id header.
links/more_info	An optional link to resources that can be helpful in solving the issue.

Invalid request error codes summary

Code	Description
not_found	Resource you are looking for was not found.
incorrect_path	Requested path was not found.
unauthorized	Required access token is missing, malformed, expired, or invalid.
insufficient_scope	The request requires higher access privileges than those provided by the access token.
rate_limit_exceeded	The api rate limit was exceeded. Contact Sell Support in order to change the rate limits for your account.
invalid_param	A request query parameter is malformed, missing, or has an invalid value
invalid_header	A header is malformed, missing, or has an invalid value.
invalid_payload	Unexpected token found when parsing the request body.
incorrect_payload	The request envelope is malformed, missing, or has an invalid value.
server_error	The authorization server encountered an unexpected condition which prevented it from fulfilling the request.
temporarily_unavailable	The authorization server is currently unable to handle the request due to maintenance or temporary overload.

Resource error codes summary

Code	Description
unknown	An attribute is not a known attribute for the resource.
missing	A required attribute must be present in the request.
already_exists	A resource with an attribute value already exists.
blank	An attribute can't be blank (neither null nor empty).
invalid_type	An attribute has an invalid type.
incorrect_value	An attribute value is incorrect e.g. is too long, has an invalid format etc.

Full example

{
  "errors": [{
    "error": {
      "resource": "Contact",
      "field": "/data/last_name",
      "code": "blank",
      "message": "attribute can't be blank",
      "details": "The attribute '/data/last_name' can't be blank (neither null nor empty)."
    },
    "meta": {
      "links": {
        "type": "error",
        "more_info": "https://developers.getbase.com/docs/rest/articles/errors"
      }
    }
  }],
  "meta": {
    "type": "errors",
    "http_status": "422 Unprocessable Entity",
    "logref": "b4bce554-8df2-48b1-9f68-a88e741463f0",
    "links": {
      "more_info": "https://developers.getbase.com/docs/rest/articles/errors"
    }
  }
}

---

HTTP status codes summary

Code	Message	Meaning
200	OK	Everything worked as expected. The response includes a non empty body.
201	Created	Everything worked as expected. Returned instead of 200 if your operation creates a new resource.
202	Accepted	Everything worked as expected. The request has been accepted for future processing. Used by asynchronous APIs.
204	No Content	Everything worked as expected. The response includes an empty body.
301	Moved Permanently	The resource you are looking for has been moved somewhere else.
304	Not Modified	The requested resource has not changed. Returned only if If-None-Match or If-Modified-Since headers were used in the request.
400	Bad Request	Returned whenever the request is missing required information or is malformed in another way, e.g. the payload is malformed.
401	Unauthorized	The API consumer credentials are invalid, e.g. the API key is revoked or the username or password is invalid.
402	Payment Required	Subscription payment is required.
403	Forbidden	The request has been refused because of insufficient user access privileges.
404	Not Found	The requested resource could not be found.
405	Method Not Allowed	The API consumer tried to access an endpoint with an invalid HTTP method, e.g. using PUT on a read-only resource.
406	Not Acceptable	The API consumer requested a format that the server cannot produce - an invalid Accept header.
409	Conflict	The request could not be completed due to a conflict with the current state of the resource. This code is only allowed in situations where it is expected the user might be able to resolve the conflict and resubmit the request.
410	The target resource is no longer available and that this condition is likely to be permanent	The position parameter expired or resources such as contact id or deal id are missing.
415	Unsupported Media Type	The API consumer used an unsupported media type in the Content-Type or Content-Encoding headers.
422	Unprocessable Entity	The request is well-formed but cannot be processed due to semantic issues with the payload, e.g. some required fields are missing.
429	Too Many Requests	The rate limit was exceeded and access is temporarily blocked.
500, 502, 503, 504	-	Something went wrong on Sell's end.