Status Codes and Errors

Response status codes

The API uses conventional HTTP status codes to indicate success or failure:

Success codes

Status code	Name	Description
200	OK	The request has succeeded.
201	CREATED	The request has succeeded and a new resource has been created as a result.
204	NO CONTENT	The request has succeeded but there is no content to send in the response for this request.

Error codes

Status code	Name	Description
400	BAD REQUEST	The server could not understand the request due to invalid syntax.
401	UNAUTHORIZED	The request has not been applied because it lacks valid authentication credentials for the target resource.
403	FORBIDDEN	The server understood the request but refuses to authorize it. Check your API key scope.
404	NOT FOUND	The requested resource doesn’t exist.
409	CONFLICT	The request conflicts with the current state of the server.
413	PAYLOAD TOO LARGE	The request entity is larger than the limits defined by the server (256 MB max for file uploads).
422	UNPROCESSABLE ENTITY	The request was well-formed but was unable to be followed due to semantic errors.
429	TOO MANY REQUESTS	You have sent too many requests in a given amount of time. See the `Retry-After` header.
500	INTERNAL SERVER ERROR	Something went wrong on the server.
503	SERVICE UNAVAILABLE	The service is temporarily unavailable. Check status.goodgrants.com for updates.

Error responses

When a request fails, the response includes an error object with details:

string

Human-readable error message.

object

Object containing specific error details, including field-level validation errors.

integer

HTTP status code.

Example error response

Response

{
  "message": "Invalid filter names and / or values.",
  "errors": {
    "invalid_filter_values": {
      "per_page": "Value must be a number. You provided [abc].",
      "category": "Value is not a valid slug. Must contain only letters and be exactly 8 characters long."
    }
  },
  "status_code": 400
}

​Response status codes

​Success codes

​Error codes

​Error responses

​Example error response

Response status codes

Success codes

Error codes

Error responses

Example error response