Errors
出售传统API使用HTTP响应代码to indicate the success or failure of an API request. In general, codes in the2xx range indicate success, codes in the4xx indicate an errorwith the provided information (errors with the information provided), and codes in the5xx range indicate a server-side error.
Header
An error response should specify theContent-Languageof the response and haveContent-Typeset to theapplication/json; charset=utf-8value.
Body
The general format of an error's envelope includes two fields:errorsandmeta. 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
Theerrorsattribute 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 themetaobject.
Error object represent either an invalid request error or a resource error.
Theerrorfields are described below:
| Name | Description |
|---|---|
code |
The error code. |
message |
Human readable error description in a language specified by theContent-Languageheader. |
details |
一个可选的详细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 responseplusHTTP response status message. |
logref |
Unique id of the request. This is the same value as theX-Request-Idheader. |
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 ifIf-None-MatchorIf-Modified-Sinceheaders 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. |
| 415 | Unsupported Media Type | The API consumer used an unsupported media type in theContent-TypeorContent-Encodingheaders. |
| 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. |