Errors

GraphQL reports errors in the response body, next to whatever data could still be returned. Check the errors array on every response.

The shape of an error#

A request that reached GraphQL is answered with HTTP 200, whether or not it succeeded. Errors are listed in errors; each names the field that failed in path.

Here a key with catalog_read but not media_read asks for a track list with download URLs:

{
  "data": {
    "release": {
      "title": "Paper Radio",
      "resources": [
        { "title": "Signal Fire", "url": null },
        { "title": "Paper Radio", "url": null }
      ]
    }
  },
  "errors": [
    {
      "message": "credential lacks the MediaRead scope",
      "locations": [{ "line": 5, "column": 7 }],
      "path": ["release", "resources", 0, "url"]
    },
    {
      "message": "credential lacks the MediaRead scope",
      "locations": [{ "line": 5, "column": 7 }],
      "path": ["release", "resources", 1, "url"]
    }
  ]
}

The titles resolved; each url did not. This is ordinary GraphQL behavior: one failing field does not void the request. When a failing field is non-nullable, the null travels up to the nearest nullable parent — for a root field, that can make data itself null.

Errors before execution#

If the query cannot be run at all, data is null and nothing executed.

Validate queries against schema.graphql at build time and you will not meet these in production.

Authentication errors#

Authorization errors#

credential lacks the <Scope> scope — the credential is valid but lacks a scope this field needs. The scope is named in the style of Viewer.scopes (CatalogRead); its wire spelling is catalog_read. See what each operation requires.

Not found is not an error#

Asking for something that does not exist, or that is not in your catalog, usually returns null or false rather than an error — and the two cases are indistinguishable on purpose, so that an API key cannot probe for other customers' data.

Validation problems are data#

publishRelease does not use errors for "this release is not ready yet". It returns published: false and a list of every problem, so you can show them all at once:

{
  "data": {
    "publishRelease": {
      "published": false,
      "problems": [
        "a UPC or GRid is required to publish",
        "no cover art"
      ]
    }
  }
}

Common errors#

Retrying#

Most mutations are safe to retry after a network failure: publishing, delivering a message, delivering a file, completing an upload, revoking a key and removing a resource all converge on the same result when repeated. Minting a key, issuing a delivery account, adding a resource and creating a party without a DPID are not — retrying them creates a second one.