Errors

HTTP statuses

If everything is ok, the response is returned with an HTTP status 200.

In case of errors, the following HTTP statuses can be used:

StatusDescription
400Bad Request from the client.
403Forbidden. The client is not allowed.
404Not Found. The resource does not exist.
409Conflict. Version control conflict.
500Internal Server Error. There is server side error. This should not happen.
503Service Unavailable. There is a temporary service migration. The call can be retried after a short delay.

Structure

The following represents a common error response resulting from a failed API request:

{
  "error": {
    "status": 400, // the HTTP status.
    "code": "11003", // WonderPush error code.
    "message": "The provided access token is invalid" // human friendly error description.

  }
}

Reference

Here are the various errors that can be returned by WonderPush, presented here ordered by code:

CodeStatusDescription
10000404No handler found
10001400When an invalid parameter is given
10002400When a mandatory parameter has been omitted
10005400When http is used for a method where https is mandatory
10006429When too many requests are received in a short time
11000400When an invalid client credentials are given
11003403The provided access token is invalid
12000404When an application does not exist
12001404When a staff member does not exist
12002404When a user does not exist
12003409When a user already exists
12009500When an unexpected error occured
12010403When a staff has not the rights for the action
12011403When a user has not the rights for the action
12012404When a staff member answers to an unexisting invitation
12013404When someone is not part of a staff as it is intended
12014400When submitting an invalid certificate
12015400When a staff member tries to use the API without having a verified email
12016404When certificate does not exist
12017400When an expected request signature is invalid
12018400When there is a security risk
12019400When using API with an unsupported platform
12020403When the provided service access token is invalid
12024404When accessing the user of a userless installation
12025400When an expected installation body is invalid
12026400When an expected user body is invalid

Pretty printing

For all endpoints returning JSON response you can append ?pretty=true to your requests to pretty print the result (use it for debugging purpose only).

Pagination

Some endpoints return multiple items at once. In that case, when relevant pagination.previous and pagination.next cursors URLs are returned in the response. You can use these cursors to navigate in both directions throughout the result items. A count parameter is also exposed to define how much items to return.
Note that these cursors are only valid for around 2 minutes, so they are only suited for iterating through a large set of results programmatically.

Partial response

If you don’t need the whole content of the response, some endpoints allow specifying a set of fields to return by setting the fields parameter. The fields parameter is given as a comma separated list of field names.

Booleans

All REST APIs parameters support providing boolean false as the values: 0, false, f, n, no, false and true as the values: 1, true, t, y, yes.

Dates and times

WonderPush exclusively uses UNIX timestamps in milliseconds (time elapsed since January 1st 1970), and expresses textual dates and times in UTC, always specifying the used timezone to avoid confusion.

You can also use a textual representation of a date using the following ISO8601 format: YYYY[-MM[-DD]][T[HH[:MM[:SS[.SSS]]]][Z|+HH[:MM[:SS[.SSS]]]]]
Here are valid examples: 2015, 2015-12, 2015-12-31, 2015-12-31T23, 2015-12-31T23:59, 2015-12-31T23:59:59, 2015-12-31T23:59:59.999.
Here are valid offsets you can also append: Z for UTC, -06, +02:00. In the absence of an offset, the date is taken as UTC. Don't forget to write T before the offset if you gave no time-part.
Unless explicitly mentioned, any missing part is taken as January 1st for date-part and midnight for the time-part.

Most API call arguments should also accept a relative date, always relative to the current time, using the following ISO8601 duration format: [+]P[nY][nM][nD][T[nH][nM][nS]] where each n represents a non-negative number.
Here are valid examples: P1Y2M3DT4H5M6S meaning 1 year 2 months 3 days 4 hours 5 minutes and 6 seconds, P1M meaning 1 month (note that there is no T before the M so it refers to months), PT5M meaning 5 minutes (note T ending the date part and starting the time part, so the M refers to minutes), P7D meaning 7 days.
You can prefix the P with an optional + sign. Such relative dates are added to the current time, hence representing a date in the future. PT5M and +PT5M represent both the date in 5 minutes.
You can prefix the P with a - sign. Such relative dates are subtracted to the current time, hence representing a date in the past. -PT5M represents the date 5 minutes ago.
For instance you can list the installations created in the last week by using GET /v1/installations?creationDateFrom=-P7D.
Unlike arguments accepting durations, a date field accepting a relative date is always relative to the time the call is made.

Any field or parameter that ends with Date expects a UNIX timestamp in millisecond as an integer, an ISO8601 formatted string, or (for most of them currently) a date interval relative to the current time.

Durations

WonderPush exclusively expresses durations in milliseconds.
But sometimes milliseconds are not really handy for human inputs. For convenience, WonderPush let’s you express duration as a human readable string comprised of an integer value followed by a unit (optionally separated by a space).
Here is a list of the units you can use:

  • Milliseconds: ms, millisecond, milliseconds (the default unit)
  • Seconds: s, sec, second, seconds
  • Minutes: m, min, minute, minutes
  • Hours: h, hr, hour, hours
  • Days: d, day, days
  • Weeks: w, week, weeks

Here are valid examples: 5s, 120 sec, 15 minutes, 36 hours, 3 day, 4 weeks.

Any field or parameter that ends with Time expects a duration expressed in milliseconds as an integer, or a string with a number and unit.

Limits

The maximum length of all the request headers is no higher than 16 KB, including the request line which contains the HTTP method, URL, query string and HTTP version.
The maximum length of the request body is 10 MB.