API: Responses

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.