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
| Status | code | Means | Retry? |
|---|---|---|---|
400 | bad_request | The request is malformed. | No. Fix the request. |
401 | unauthorized | GovDash didn't accept the API key. | No. Fix the key. |
402 | quota_exceeded | Your team has used up a quota, such as agent credits. | No. |
403 | forbidden | The key can't do this. | No. |
404 | not_found | The key can't see the record. | No. |
409 | conflict | A record like this already exists. | No. Use the existing record. |
413 | payload_too_large | The request body is over 1 MB. | No. Send less data. |
422 | validation_failed | The request is well formed, but GovDash's rules rejected it. | No. Fix the value. |
429 | rate_limited | You hit a rate limit. | Yes, after retry-after. |
500 | internal_error | Something went wrong in GovDash. | Yes, with backoff. Check before a POST. |
503 | service_unavailable | GovDash 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
PATCHbody is empty. Send at least one field. - A
cursorwas 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.
| Endpoint | Conflicts when |
|---|---|
POST /v1/opportunities | An 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_idisn't a phase fromGET /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.
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}`)
}
}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.