GovDash
Menu

Errors

GovDash uses HTTP status codes to say whether a request worked. 2xx means it succeeded, 4xx means something about the request needs to change, and 5xx means something went wrong on GovDash's side. Every error has the same JSON body, so you can handle them all in one place.

Error body

{
  "error": {
    // Stable and machine-readable. Branch on this.
    "code": "not_found",
    // For people and logs. The wording can change, so don't parse it.
    "message": "The requested resource was not found.",
    "request_id": "6f1c1f0e-5d0b-4f0e-9a52-3b0f6c0d7a41",
  },
}

Every /v1 response, successful or not, carries an x-request-id header. Error bodies repeat it as error.request_id. Log it with each request you make. When you contact support, send the request ID, never the request or response body, because bodies can contain controlled unclassified information (CUI).

Some 429 responses add error.bucket. See Rate limits. Ignore fields you don't recognize. We may add more.

Error codes

StatuscodeMeansRetry?
400bad_requestThe request is malformed.No. Fix the request.
401unauthorizedGovDash didn't accept the API key.No. Fix the key.
402quota_exceededYour team has used up a quota, such as agent credits.No.
403forbiddenThe key can't do this.No.
404not_foundThe key can't see the record.No.
409conflictA record like this already exists.No. Use the existing record.
413payload_too_largeThe request body is over 1 MB.No. Send less data.
422validation_failedThe request is well formed, but GovDash's rules rejected it.No. Fix the value.
429rate_limitedYou hit a rate limit.Yes, after retry-after.
500internal_errorSomething went wrong in GovDash.Yes, with backoff. Check before a POST.
503service_unavailableGovDash is briefly unable to serve the request.Yes, after retry-after.

Each endpoint's page in the API reference lists the statuses it can return.

400 bad request

The request doesn't match what the endpoint accepts. The message names the part of the request that failed: Invalid request path parameters:, Invalid request query parameters:, Invalid request headers:, or Invalid request body:, followed by what was wrong.

Common causes:

  • The body isn't valid JSON, or a field has the wrong type.
  • The body has a field the endpoint doesn't accept. Request bodies are strict.
  • A PATCH body is empty. Send at least one field.
  • A cursor was changed or came from a different list.
  • An expand[] value isn't one the endpoint supports.
{
  "error": {
    "code": "bad_request",
    "message": "Invalid request body: Expected a value with at least 1 entry"
  }
}
{
  "error": {
    "code": "bad_request",
    "message": "The cursor is invalid. Pass an `endCursor` or edge `cursor` unchanged."
  }
}

401 unauthorized

GovDash didn't accept the API key. See Authentication.

402 quota exceeded

Your team has used up something it pays for, such as the credits an agent run needs. Retrying won't help until the quota resets or your team adds more. Talk to your GovDash admin.

403 forbidden

GovDash accepted the key, but it isn't allowed to do this. Usually the service account's role is missing a permission:

{
  "error": {
    "code": "forbidden",
    "message": "You do not have permission to perform this action."
  }
}

Give the service account a role with the permission it needs. Don't switch it to an admin role to make the error go away. A 403 can also mean your team's access to GovDash has ended, or that you tried to create a record with a classification above your key's ceiling. See Classification.

Some 403 responses use the code classification_out_of_scope. Handle it the same way as forbidden.

404 not found

The key can't see the record. It might not exist, it might belong to another team, or it might be classified above what the key can read. GovDash returns the same response in all three cases, so a response never reveals that a record you can't read exists.

{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found."
  }
}

409 conflict

A record may conflict with the change, or an existing reference may prevent deletion. Read the error message, then update the conflicting record or remove the reference if appropriate before retrying. For agent run idempotency, 409 can also mean the earlier request is still in progress; see Retry safely.

EndpointConflicts when
POST /v1/opportunitiesAn opportunity with the same title exists.
POST /v1/people, PATCH /v1/people/{id}A person with the same name or details exists.
POST /v1/agencies, PATCH /v1/agencies/{id}An agency with the same name exists.
{
  "error": {
    "code": "conflict",
    "message": "An opportunity with this title already exists."
  }
}

413 payload too large

Request bodies can be at most 1 MB. GovDash closes the connection after a 413. If you send a body with chunked transfer encoding and it goes over 1 MB, GovDash resets the connection, and your HTTP client reports a network error instead of a 413.

422 validation failed

The request has the right shape, but GovDash's business rules rejected a value in it. A 400 means "this isn't a valid request." A 422 means "this is a valid request, but GovDash won't make this change." For example:

  • The new phase requires fields the opportunity doesn't have yet.
  • You tried to delete a contract that GovDash is still processing.
  • phase_id isn't a phase from GET /v1/meta/phases.

When GovDash can say what's wrong, the message does:

{
  "error": {
    "code": "validation_failed",
    "message": "Missing required field in Qualify: Contract vehicle"
  }
}

Other times the message is generic, The request failed validation. A 422 has no per-field list, so show error.message to a person or log it, and don't parse it.

429 rate limited

You sent too many requests. Wait the number of seconds in the retry-after header, then retry. See Rate limits.

500 internal error

Something went wrong inside GovDash. Usually that means a bug on our side, not a problem with your request.

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred."
  }
}

A 500 can arrive after a write already happened, so check before you retry a POST. See Retry safely. Check status.govdash.com for known incidents. If a request keeps failing with 500, email [email protected] with the request ID from the x-request-id header and we'll dig in. Don't send the request body.

503 service unavailable

GovDash is briefly unable to serve the request, for example while a service it depends on restarts. GovDash didn't run the request, so it's always safe to retry. Wait the number of seconds in the retry-after header first. Check status.govdash.com for known incidents.

{
  "error": {
    "code": "service_unavailable",
    "message": "The service is temporarily unavailable. Try again later."
  }
}

Handle errors

Retry rate_limited, service_unavailable, and internal_error with backoff, as Retry safely describes. Treat not_found as a record you can't see. Surface everything else, because retrying won't fix it.

errors.tsTypeScript
const apiVersion = process.env.GOVDASH_API_VERSION
if (!apiVersion) throw new Error("Set GOVDASH_API_VERSION")

type ApiError = {
  error: {
    code: string
    message: string
    request_id?: string
    bucket?: "token" | "team"
  }
}

const id = process.env.OPPORTUNITY_ID

const response = await fetch(
  `${process.env.GOVDASH_API_URL}/v1/opportunities/${id}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.GOVDASH_API_KEY}`,
      "govdash-version": apiVersion,
    },
  },
)

if (!response.ok) {
  const { error } = (await response.json()) as ApiError
  switch (error.code) {
    case "rate_limited":
    case "service_unavailable":
    case "internal_error":
      console.warn("Retry with backoff")
      break
    case "not_found":
      console.warn("The record is gone, or this key can't see it")
      break
    default:
      throw new Error(`${response.status} ${error.code}: ${error.message}`)
  }
}
errors.pyPython
import os

import requests

opportunity_id = os.environ["OPPORTUNITY_ID"]

response = requests.get(
    f"{os.environ['GOVDASH_API_URL']}/v1/opportunities/{opportunity_id}",
    headers={
        "Authorization": "Bearer " + os.environ["GOVDASH_API_KEY"],
        "govdash-version": os.environ["GOVDASH_API_VERSION"],
    },
)

if not response.ok:
    error = response.json()["error"]
    if error["code"] in ("rate_limited", "service_unavailable", "internal_error"):
        print("Retry with backoff")
    elif error["code"] == "not_found":
        print("The record is gone, or this key can't see it")
    else:
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']}")

The 413 from a chunked upload over 1 MB never arrives as JSON, so catch network errors too.

Seeing an error you can't explain? Email [email protected] with the request ID.