Error Handling

The First Street API will return HTTP 200 for all valid requests to the API. Valid requests are any queries that satisfy type requirements within the GraphQL schema. Valid requests may or may not yield data and may or many not contain field errors.

When making a successful request to the GraphQL API, an object is returned:

{
    "data": { ... }
}

Where data represents the requested query that is provided. In cases where there is an error, an error field will appear. This field is an array of an Error Message:

{
    "errors": [...],
    "data": { ... }
}

In the event of a field specific error, data will still resolve with the query result and errors will be populated with an error message.

Error Message

Error message are standardized objects that returned in the event of an error. All keys may be optional so they may or may not be returned, depending on the error.

Key	Type	Description
message	string	A user friendly error message
locations	array	An array that defines the line and column of the error
extensions	object	Internal code of why the request could have failed
path	array[string]	An array that explains which part of the query the error occured on

Example - Successful Error

A typical error you may receive is node-specific access, where access to a specific field within the API may not be granted due to contractual obligations. Consider the following query:

query {
  propertyByAddress(address:"247 Water Street Brooklyn NY") {
    fsid
    flood {
      floodFactor
    }
    heat {
      heatFactor
    }
  }
}

This query asks for a floodFactor and heatFactor for a particular property. In the event that the user requesting this information does not have access to heatFactor, the following response will be returned:

{
  "errors": [
    {
      "message": "Error 15: Your account has no access to this node. Please contact [e-mail] for more information.. RequestID: 48c215c0356d24eef17477b88c69a7a3",
      "path": [
        "propertyByAddress",
        "heat"
      ]
    }
  ],
  "data": {
    "propertyByAddress": {
      "fsid": 362104205,
      "flood": {
        "floodFactor": 1
      },
      "heat": null
    }
  }
}

message describes the issue while path provides an array of strings that maps where the query could have possibly failed. In this example the query that should be removed is heat { heatFactor } because the user does not have access to the fields. Alternatively, you may email [e-mail] if you believe this field should be enabled for your account.

Example - Malformed Query

In the event of malformed queries, where queries are not following the GraphQL schema, HTTP 422 will occur. Consider the following query:

query {
  propertyByAddress(address:"247 Water Street Brooklyn NY") {
    fsid
    APN
    flood {
      floodFactor
    }
    heat {
      riskDirection
    }
  }
}

Because riskDirection does not exist within the property.heat field, the query is unprocessable. The following error will be returned:

{
  "errors": [
    {
      "message": "Cannot query field \"riskDirection\" on type \"PropertyHeat\".",
      "locations": [
        {
          "line": 9,
          "column": 7
        }
      ],
      "extensions": {
        "code": "GRAPHQL_VALIDATION_FAILED"
      }
    }
  ],
  "data": null
}

In this scenario, data will be completely null and the response is considered invalid. Please double check queries before sending another request.