Error Codes & Troubleshooting

All ComplianceGrid API errors follow a consistent JSON format. This page covers HTTP status codes, application error codes, and common troubleshooting steps.

Reading time: 5 minLast updated: Feb 2026

Error Response Format

All error responses return a consistent JSON structure with a success: false flag, an error code, human-readable message, and optional details.

error-response.json

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "parties[0].name",
        "message": "Required field 'name' is missing",
        "type": "required"
      },
      {
        "field": "parties[0].country",
        "message": "Must be a valid ISO 3166-1 alpha-2 country code",
        "type": "format"
      }
    ]
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2026-02-22T15:30:00Z"
  }
}

Tip: Always log the meta.requestId — include it when contacting support for faster debugging.

HTTP Status Codes

200

Request succeeded. Response body contains the requested data.

201

Created

Resource created successfully (e.g., AES filing draft).

400

Bad Request

Invalid request body, missing required fields, or malformed parameters.

401

Unauthorized

Missing or invalid API key / Bearer token.

403

Forbidden

Valid credentials but insufficient permissions or unsubscribed API.

404

Not Found

Endpoint or resource does not exist.

409

Conflict

Resource already exists or state conflict (e.g., duplicate filing).

422

Unprocessable Entity

Request is well-formed but semantically invalid (e.g., invalid HTS code format).

429

Too Many Requests

Rate limit exceeded. Check Retry-After header.

500

Internal Server Error

Unexpected server error. Retry with exponential backoff.

502

Bad Gateway

Upstream government data source temporarily unavailable.

503

Service Unavailable

API is temporarily down for maintenance. Check /status.

Application Error Codes

These codes appear in the error.code field and provide more specific context than the HTTP status alone.

Code	HTTP	Description	Fix
INVALID_API_KEY	401	The API key is malformed or does not exist.	Check the key prefix (cg_sk_ or cg_pk_) and verify in the Developer Portal.
EXPIRED_TOKEN	401	The Bearer token has expired.	Request a new token via POST /oauth/token.
SUBSCRIPTION_REQUIRED	403	You are not subscribed to this API vertical.	Go to Developer Portal → Subscriptions and subscribe to the required API.
ENVIRONMENT_MISMATCH	403	Sandbox key used on production endpoint or vice versa.	Use cg_sk_ keys with sandbox.api.compliancegrid.ai and cg_pk_ keys with api.compliancegrid.ai.
RATE_LIMIT_EXCEEDED	429	Too many requests in the current window.	Wait for the Retry-After duration and implement exponential backoff.
INSUFFICIENT_CREDITS	402	Production credit balance is zero or negative.	Add credits via Dashboard → Billing → Purchase Credits.
VALIDATION_ERROR	400	One or more request fields failed validation.	Check the 'details' array in the error response for specific field errors.
RESOURCE_NOT_FOUND	404	The requested record (filing, entity, etc.) was not found.	Verify the ID or reference number is correct.
UPSTREAM_UNAVAILABLE	502	A government data source (trade.gov, SEC, etc.) is temporarily unreachable.	Retry after a few seconds. The API falls back to cached data when available.
FILING_STATE_INVALID	409	AES filing is in a state that does not allow the requested action.	Check the filing status — e.g., only VALIDATED filings can be submitted.

Common Troubleshooting

Getting 401 but my key looks correct

Ensure you're passing a valid Bearer token in the Authorization header (e.g., Authorization: Bearer <token>).
Check for trailing whitespace or newline characters in the key.
Verify the key hasn't been revoked in the Developer Portal.
Sandbox keys must hit sandbox.api.compliancegrid.ai, not the production endpoint.

Getting 403 Subscription Required

Go to Developer Portal → Subscriptions.
Subscribe to the specific API vertical you're trying to call.
Or click 'Subscribe to All' to enable all 12 verticals at once.
Note: Subscription changes take effect immediately.

Getting empty results from sandbox

Sandbox returns canned mock data for specific test queries.
Try screening 'Huawei Technologies' for guaranteed hits.
Check the response meta.environment field to confirm you're hitting sandbox.

Getting 502 errors intermittently

This means an upstream government data source is temporarily unavailable.
Implement retry logic with exponential backoff (see Rate Limits docs).
Check the /status page for known outages.
The API automatically falls back to cached data when possible.

SDK Error Handling

error-handling.ts

import ComplianceGrid from "@compliancegrid/sdk";

const cg = new ComplianceGrid({
  apiKey: process.env.COMPLIANCEGRID_API_KEY,
});

try {
  const result = await cg.compliance.screenParties([
    { name: "Huawei", country: "CN" }
  ]);
  console.log(result.data);
} catch (err) {
  if (err.status === 429) {
    console.log("Rate limited, retry after:", err.retryAfter);
  } else if (err.status === 401) {
    console.log("Invalid API key");
  } else {
    console.error("API error:", err.code, err.message);
  }
}

error_handling.py

from compliancegrid import ComplianceGrid, ApiError

cg = ComplianceGrid(api_key=os.environ["COMPLIANCEGRID_API_KEY"])

try:
    result = cg.compliance.screen_parties([
        {"name": "Huawei", "country": "CN"}
    ])
    print(result["data"])
except ApiError as e:
    if e.status == 429:
        print(f"Rate limited, retry after: {e.retry_after}")
    elif e.status == 401:
        print("Invalid API key")
    else:
        print(f"API error: {e.code} - {e.message}")

Rate Limits

Limits, headers, and retry strategies

Authentication

API keys and OAuth 2.0 flow