Crime Data API Authentication, Quotas, and Errors

Start with one request from your backend or terminal. The ZIP and coordinate integration guide includes working request formats. Keep the HTTP status, JSON error code, and message available when diagnosing a failure. Branch application logic on status and error code; message wording can change.

Check the key and its organization

Score and incident requests need a secret cs_secret_ key in the x-api-key header. Send the key itself, without a Bearer prefix, quotes, or trailing whitespace.
Keep that secret on your server. Publishable cs_pub_ keys belong in the hosted map embed and cannot authenticate REST score calls.
The key belongs to the organization selected when it was created. Switching organizations in the dashboard does not move the key or its usage. Check that organization's access and allowance in the dashboard.
Production uses https://api.crimescore.io/v1. Development uses https://api.dev.crimescore.io/v1 and its own keys. Public GET /v1/geocode does not require a key or consume quota.

Evaluation access and paid allowances

When evaluation access is available, the published offer is 25 credits for 30 days in a new account's initial organization, without a payment method. These published evaluation credits do not renew. The dashboard shows your actual allowance, expiry, and enabled capabilities; those can differ from the published offer.

Score Details is included on Starter and higher plans and can be enabled for evaluation access. Nearby Incidents is included on Pro and Enterprise; it is not part of the default evaluation capability list. Creating another key does not create another organization allowance.

Starter: 500 API requests per month under the published plan.
Pro: 2,500 API requests per month under the published plan.

Successful Score and Score Details calls each consume one request. Dashboard reports use the same organization's allowance and can consume multiple credits. The separate Starter subscription trial and current paid options are explained on the pricing page.

Authentication and access errors

Response	What to check
401 `UNAUTHORIZED`	Confirm the header, environment, and active key first. A valid key can also fail when its organization no longer has usable access, such as after evaluation expiry, or when the organization is suspended. A publishable key can also return 401 when its domain or free-access restrictions reject the request; always use a secret key for REST calls. Check dashboard access before assuming the key was mistyped.
403 `SECRET_KEY_REQUIRED`	Replace the publishable embed key with a server-side secret key.
403 `CAPABILITY_NOT_INCLUDED`	The route is outside your current free capability list. Check the enabled evaluation capabilities or choose a plan that includes it.
403 `QUOTA_EXCEEDED`	The active allowance is exhausted. Inspect usage in the key's organization. Repeating the request will not replenish credits; review the reset date or available plan options.
403 `FORBIDDEN`	The handler can return this when a paid tier does not include the route. Read the message and compare the requested endpoint with the organization's current plan.

Expired access and exhausted credits are different states. An exhausted but still-active allowance can return 403 QUOTA_EXCEEDED; access that has ended can return 401 UNAUTHORIZED. The status alone does not tell you whether someone should replace a key or review their subscription.

Input, coverage, and service errors

Response	What to do
400 `INVALID_PARAMETERS`	Send either a five-digit ZIP or both latitude and longitude, never both modes. Keep ZIP codes as strings. The optional `component` belongs only on `/score/details` and must use a documented value.
404 `NO_COVERAGE` / `NO_SCORE_DATA`	No matching geography or score is available for the input. Show an unavailable state rather than zero or a reassuring default. Check the location and coverage limitations.
404 `NO_COMPONENT_DATA`	The requested component has no data. Keep its unavailable state separate from a successful overall score.
404 `NOT_FOUND`	Check the hostname, `/v1` base path, route, and HTTP method. This is a missing route, not a location-coverage response.
429 `RATE_LIMITED`	For short-term request throttling, slow down and reduce concurrency; use bounded backoff if you retry. Action-based geocoding search also has daily and monthly caps that can require a longer wait for reset. These limits are separate from the organization's score-request allowance.
500 `INTERNAL_ERROR` / `SERVER_ERROR`	Keep the failure visible and capture diagnostic information. If it persists, contact support. Do not treat an error as a successful score.

Handle uncertain results without retry loops

A network timeout can happen after the server charges a successful lookup. Check usage before repeating an uncertain request. Do not automatically retry authentication, capability, quota, or invalid-input errors: fix the underlying condition first. Log the status and error code without logging the API key, and avoid sending private addresses to unrelated analytics tools.

If you need help, contact CrimeScore with the UTC timestamp, endpoint, HTTP status, error code, and request ID if available. Include enough non-sensitive location context to reproduce a coverage problem. Never include your secret key. Use the API reference and OpenAPI contract for the request and response schemas.