Errors | Tradespace | Developer Documentation

The API reports errors in two ways, depending on where the request fails.

Request Errors

If the request is rejected before the query runs, the API returns an HTTP error status.

Status	Meaning
`400 Bad Request`	The request has no operation name. Name the query and send the name in `operationName`.
`401 Unauthorized`	The API key is missing, unknown, or inactive, or it was created in a different region than the endpoint.
`429 Too Many Requests`	The hourly rate limit is exhausted. See Rate limits.

The API returns three kinds of 400. Only the missing-operation-name case uses an actual HTTP 400. The other two come back as HTTP 200 with 400 in extensions.status.

Missing operation name (HTTP 400), rejected before GraphQL runs:

{
  "errors": [
    {
      "message": "Operation name is required",
      "extensions": {
        "code": "BAD_REQUEST",
        "status": 400,
        "request_id": "f295efec-3cb1-4ac0-9a43-70d559b7fd76"
      }
    }
  ]
}

Query validation error (HTTP 200), e.g. an unknown field. The query never runs, so there’s no data key, and graphql-ruby’s own code is kept:

{
  "errors": [
    {
      "message": "Field 'notAField' doesn't exist on type 'ContactCollection'",
      "locations": [{ "line": 1, "column": 29 }],
      "path": ["query Contacts", "contacts", "notAField"],
      "extensions": {
        "code": "undefinedField",
        "typeName": "ContactCollection",
        "fieldName": "notAField",
        "status": 400,
        "request_id": "f295efec-3cb1-4ac0-9a43-70d559b7fd76"
      }
    }
  ]
}

Bad argument during execution (HTTP 200), e.g. an invalid sortField:

{
  "data": null,
  "errors": [
    {
      "message": "sortField must be one of: name, created_at, updated_at",
      "locations": [{ "line": 1, "column": 18 }],
      "path": ["contacts"],
      "extensions": {
        "code": "BAD_REQUEST",
        "status": 400,
        "request_id": "f295efec-3cb1-4ac0-9a43-70d559b7fd76"
      }
    }
  ]
}

There are two 401 responses. Both use HTTP 401 and come back before GraphQL runs.

A missing, invalid or inactive API key:

{
  "errors": [
    {
      "message": "The API key is missing, invalid, or inactive",
      "extensions": {
        "code": "UNAUTHORIZED",
        "status": 401,
        "request_id": "f295efec-3cb1-4ac0-9a43-70d559b7fd76"
      }
    }
  ]
}

A valid key whose account is disabled or no longer has app access:

{
  "errors": [
    {
      "message": "You need an active account to access our API",
      "extensions": {
        "code": "ACCOUNT_INACTIVE",
        "status": 401,
        "request_id": "f295efec-3cb1-4ac0-9a43-70d559b7fd76"
      }
    }
  ]
}

A rate-limited request gets an HTTP 429. It carries the two rate-limit headers, with Remaining at 0, and a Retry-After header with the number of seconds until the limit resets:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0

{
  "errors": [
    {
      "message": "Rate limit exceeded. Try again later.",
      "extensions": {
        "code": "TOO_MANY_REQUESTS",
        "status": 429,
        "request_id": "f295efec-3cb1-4ac0-9a43-70d559b7fd76"
      }
    }
  ]
}

Include the request_id when you contact Tradespace support about a failed request.

GraphQL Errors

Once the query runs, the response is 200 OK even when part of it fails. Failures appear in the errors array. Each error’s extensions.status holds an HTTP-style status. A failing field that can be null resolves to null. Single-record queries such as disclosure or patent cannot be null, so when one of them fails the whole data value is null.

`extensions.status`	Meaning
`400`	An argument is invalid, for example a `sortField` the query does not support. The message lists the allowed values.
`403`	Your account is not allowed to read this record or module.
`404`	No record matches the ID or number you passed.
`500`	Server-side failure

If you’re getting 500 errors, check status.tradespace.io for outages.

400 invalid argument value:

{
  "data": { "contacts": null },
  "errors": [
    {
      "message": "sortField must be one of: name, createdAt, updatedAt",
      "locations": [{ "line": 1, "column": 18 }],
      "path": ["contacts"],
      "extensions": {
        "status": 400,
        "code": "BAD_REQUEST",
        "request_id": "f295efec-3cb1-4ac0-9a43-70d559b7fd76"
      }
    }
  ]
}

403 feature not enabled or not authorized:

{
  "data": { "opportunities": null },
  "errors": [
    {
      "message": "You are not authorized to perform this action",
      "locations": [{ "line": 1, "column": 22 }],
      "path": ["opportunities"],
      "extensions": {
        "status": 403,
        "code": "FORBIDDEN",
        "request_id": "f295efec-3cb1-4ac0-9a43-70d559b7fd76"
      }
    }
  ]
}

404 record not found:

{
  "data": { "contact": null },
  "errors": [
    {
      "message": "Contact not found",
      "locations": [{ "line": 1, "column": 27 }],
      "path": ["contact"],
      "extensions": {
        "status": 404,
        "code": "NOT_FOUND",
        "request_id": "f295efec-3cb1-4ac0-9a43-70d559b7fd76"
      }
    }
  ]
}

500 server-side failure (e.g. a non-null field resolved to null):

{
  "data": { "contacts": { "metadata": null } },
  "errors": [
    {
      "message": "Cannot return null for non-nullable field CollectionMetadata.count",
      "locations": [{ "line": 1, "column": 40 }],
      "path": ["contacts", "metadata", "count"],
      "extensions": {
        "code": "INTERNAL_SERVER_ERROR",
        "status": 500,
        "request_id": "f295efec-3cb1-4ac0-9a43-70d559b7fd76"
      }
    }
  ]
}

Always check errors before reading data.