API: Responses
- Overview
- Quick start
- Various Topics
- Manage Results
- Core Resources
- Other resources
Summary
Yombo uses standard HTTP response codes to to signify various events. See the Error Responses below for explanation for any error results.
The responses are always in JSON API format. The following 4 keys are available in the JSON response:
- 'data' - This key is always returned, except on error. The data you are looking for is located here. This can be an array of associative arrays for multiple items, or a single associative array.
- 'meta' - Contains various details about the results, such as count, number of pages of data available, etc.
- 'links' - Provides links for the next page, previous page, last page, and first page, as well as the current page of results. See Pagination for details.
- 'included' - An optional item that is when other referenced items are included in the results. For example, if the devices are being requested and the gateway the associated gateway or device variables are to be returned with the result set, they will be made available here.
Success HTTP Codes
Code | Meaning |
---|---|
200 Ok |
Request processed normally. |
201 Created |
Content was created. |
Error Responses
When things do go as planned, the API will return an error response, generally with detailed information about the error. See below for Error Response Codes for additional information.
When an error occurs, the API will set the most appropriate HTTP response code. Additionally, it will include the following keys:
- 'error' - An array of associated arrays that details all the errors encountered while processing the request. Each error will include:
- 'code' - A string for the specific code. This is used internally by Yombo to locate the error. Some errors will include even more information in the meta section of the result with the same code.
- 'title' - High level error message.
- 'deetail' - More detailed information about the error.
- 'meta' - Additional information regarding the errors. Typically, this is used by applications to collect information from the API that be displayed to the user.
Error Response Codes
HTTP response codes provide the reason for the failure at a high level.
Error Code | Meaning |
---|---|
400 Bad Request |
Something was bad with your request. |
401 Unauthorized |
Bad API key or no user user authentication. |
403 Forbidden |
You were authenticated, but you do not have access to resource. |
404 Not Found |
The specified resource could not be found |
405 Method Not Allowed |
You tried to access a resource with an invalid method |
406 Not Acceptable |
You requested a format that isn’t json, msgpack, or xml. |
409 Conflict |
Request could not be completed due to conflict, usually from a duplicate record or field within a record. |
410 Gone |
The requested item has been removed from our servers |
418 I’m a teapot |
You did something silly, so we laughing about it over tea and crackers. |
429 Too Many Requests |
You’re requesting too many cheesy poofs! Slow down! |
500 Internal Server Error |
We had a problem with our server. Try again later. |
503 Service Unavailable |
We’re temporarily offline for maintenance. Please try again later. |
Error Message Codes
Unless the request was highly malformed, most responses will include error_codes which details the reason for the error. The message codes can also contain what field or specific item that caused the error.
Many errors will return error codes within the response.
Error Code | Has Data |
Description |
---|---|---|
dns-too-soon | Yes | Tried to change DNS information too soon. Data contain EPOCH time when the value can be changed. |
duplicate-entry | Yes | When a field with an existing value already exists. Usually checked on only labels and machine_labels. |
not-found | Yes | When an item isn’t found, includes what can’t be found. |
invalid-filter-operator | Yes | Returns when _filteroperator is invalid. See: Filter Operator
|
invalid-filter-comparator | No | The comparator within a fitler field is invalid. See: Filters |
invalid-id | Yes | Returns the ID that is invalid. |
invalid-input | Yes | When input isn’t formated correctly. Returns the field submitted and it’s value. |
unchangeable-field | Yes | Returned when a field’s value is immutable. |