Skip to main content
The API uses standard HTTP status codes and returns a consistent error envelope for all error responses.

​
Error format

{
  "error": {
    "code": "not_found",
    "message": "The requested contract does not exist or is not accessible",
    "request_id": "req_abc123def456"
  }
}
FieldDescription
codeMachine-readable error code (see table below)
messageHuman-readable description of the error
request_idUnique identifier for this request. Include this when contacting support.

​
Error codes

HTTP StatusCodeDescription
400validation_failedInvalid query parameters or request format
401unauthorizedMissing or invalid API key
403forbiddenValid key but resource is outside your partner scope
404not_foundResource does not exist or is not accessible
429rate_limitedToo many requests. See Rate Limits
500internal_errorSomething went wrong on our end

​
Handling errors

const response = await fetch(url, { headers });

if (!response.ok) {
  const body = await response.json();
  const { code, message, request_id } = body.error;

  switch (code) {
    case "rate_limited":
      const retryAfter = response.headers.get("Retry-After");
      // Wait and retry
      break;
    case "unauthorized":
      // Check your API key
      break;
    case "not_found":
      // Resource doesn't exist or isn't in your scope
      break;
    default:
      console.error(`API error [${request_id}]: ${code} - ${message}`);
  }
}

​
Request IDs

Every response includes an X-Request-ID header. When reporting issues, include this ID so we can trace the exact request in our logs. 
curl -v https://prod-api.civicmarketplace.com/v1/contracts/ctr_invalid \
  -H "Authorization: Bearer cmp_live_YOUR_KEY"

# Response headers will include:
# X-Request-ID: req_abc123def456