API Errors

API clients should be prepared to receive HTTP errors in response to API calls.


HTTP Errors in the 5xx series should generally be re-tried using an exponential backoff. The provided API clients handle this for you.


Clients should also be resilient to arbitrary response content: intermediate proxies and load balancers may produce HTML error messages rather than the expected valid JSON.

API-Specific Errors

Errors returned from the API implementation have a JSON body with the following format:

  "code": "TooManyFoos",
  "message": "You can only have 3 foos\n----\nmethod: toomanyfoos\nerrorCode: TooManyFoos\nstatusCode: 472 \ntime: 2017-01-22T21:20:16.650Z",
    "method": "toomanyfoos",
    "params": {},
    "payload": {"foos":[4, 5]},
    "time": "2017-01-22T21:20:16.650Z",

The code property identifies the error itself. The codes that are common to all services (defined in taskcluster-lib-api) are described below, but specific services may add additional service-specific error codes, documented in the reference section.

The message is suitable for display to users. It contains a detailed error message and some basic information about the request.

The additional requestInfo fields describe the request that caused the error in more detail, and may be useful for "advanced" users. The included payload may have been modified to remove potentially sensitive information, and can be safely shown to the user in an error message.

MalformedPayload: 400

The method expects a payload, but the request body was not JSON

InvalidRequestArguments: 400

The provided query strings or parameters are invalid

InputValidationError: 400

The payload was valid JSON, but did not match the documented schema

InputError: 400

The input was invalid for some other reason (described in the message)

AuthenticationFailed: 401

Hawk authentication failed. The corresponding message is generally very terse, to avoid providing extra information that might help an attacker guess valid credentials.

InsufficientScopes: 403

The hawk authentication succeeded (or there was no Hawk header), but the scopes associated with that authentication were not sufficient for the requested operation.

ResourceNotFound: 404

The requested resource wasn't found

RequestConflict: 409

The request conflicts with server state. This can occur when a "create" operation occurs for a resource that already exists. Most "create" operations are idempotent, meaning that two create calls for exactly the same resource will both succeed, but if the two calls specify different payloads, a RequestConflict error will result.

ResourceExpired: 410

The resource existed, but has expired.

InputTooLarge: 413

The provided payload is too big.

InternalServerError: 500

An internal error occurred. The error message is not returned, lest it expose security-sensitive issues, but is logged and available to Taskcluster administrators.