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.

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.

Any field or parameter that ends with Date expects a UNIX timestamp in millisecond as an integer, or an ISO8601 formatted string.

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 64 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.