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:

Status	Description
400	Bad Request from the client.
403	Forbidden. The client is not allowed.
404	Not Found. The resource does not exist.
409	Conflict. Version control conflict.
500	Internal Server Error. There is server side error. This should not happen.
503	Service 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:

Code	Status	Description
10000	404	No handler found
10001	400	When an invalid parameter is given
10002	400	When a mandatory parameter has been omitted
10005	400	When http is used for a method where https is mandatory
10006	429	When too many requests are received in a short time
11000	400	When an invalid client credentials are given
11003	403	The provided access token is invalid
12000	404	When an application does not exist
12001	404	When a staff member does not exist
12002	404	When a user does not exist
12003	409	When a user already exists
12009	500	When an unexpected error occured
12010	403	When a staff has not the rights for the action
12011	403	When a user has not the rights for the action
12012	404	When a staff member answers to an unexisting invitation
12013	404	When someone is not part of a staff as it is intended
12014	400	When submitting an invalid certificate
12015	400	When a staff member tries to use the API without having a verified email
12016	404	When certificate does not exist
12017	400	When an expected request signature is invalid
12018	400	When there is a security risk
12019	400	When using API with an unsupported platform
12020	403	When the provided service access token is invalid
12024	404	When accessing the user of a userless installation
12025	400	When an expected installation body is invalid
12026	400	When 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.

See more information and sample code.

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.