API: Responses

From Yombo
Jump to: navigation, search


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
Request processed normally.
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
Bad Request
Something was bad with your request.
Bad API key or no user user authentication.
You were authenticated, but you do not have access to resource.
Not Found
The specified resource could not be found
Method Not Allowed
You tried to access a resource with an invalid method
Not Acceptable
You requested a format that isn’t json, msgpack, or xml.
Request could not be completed due to conflict, usually from a duplicate record or field within a record.
The requested item has been removed from our servers
I’m a teapot
You did something silly, so we laughing about it over tea and crackers.
Too Many Requests
You’re requesting too many cheesy poofs! Slow down!
Internal Server Error
We had a problem with our server. Try again later.
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


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.