DocketLayer API Error Reference
DocketLayer returns standard HTTP status codes across all endpoints. Errors include a machine-readable code field and a human-readable message. This reference covers every error class, what causes it, and the appropriate handling strategy.
4xx Client Errors
400 Bad Request — The request is malformed. Common causes: missing required parameters, invalid court code format, unparseable date strings. Check the message field for the specific parameter that failed validation. These errors are not retryable without fixing the request.
404 Not Found — The requested case does not exist in DocketLayer's index, or the court code is not recognized. Check that the court code is correct using the /v2/status endpoint. A 404 on a valid court code means the case number was not found in that court's docket.
422 Unprocessable Entity — The court exists but coverage is not yet active. Courts with coverage='planned' return 422 rather than 404 to distinguish "court is known but not yet supported" from "case not found." No retry will help — coverage must be enabled for the court before queries succeed.
429 Too Many Requests — Rate limit exceeded. The response includes Retry-After in seconds. Back off and retry after the indicated interval. DocketLayer applies rate limits per wallet address.
Payment Errors (402)
402 Payment Required — No payment was included with the request. This is the normal x402 probe response, not an error in the failure sense. The response includes an X-Payment-Requirements header containing the payment specification as JSON. The key fields are payTo (destination wallet address), maxAmountRequired (in USDC base units — 990000 for $0.99), network (always solana-mainnet), and asset (the USDC mint address).
Construct a signed Solana USDC transfer, wrap it in an x402 payment payload, base64-encode it, and retry with the x402-payment header. See the How x402 Works guide for the full implementation.
If a 402 is returned on a request that included an x402-payment header, the payment was rejected. Reasons include: the transaction has already been used (replay attempt), the payment amount does not match the current price, the blockhash is expired (Solana transaction signatures are valid for approximately 5 minutes), or the transaction signature is invalid. The code field in the response body specifies the rejection reason.
5xx Server Errors
500 Internal Server Error — An unexpected error occurred. These are not caused by the request content. Retry with exponential backoff. If the error persists across multiple retries over several minutes, it indicates an infrastructure issue.
502 Bad Gateway — The upstream court system returned an invalid response. This can occur during court maintenance windows or when a court portal changes its response format in a way that breaks parsing. DocketLayer's normalization service monitors for this and deploys selector updates, but there is a window where 502s can occur. Retry with backoff; most 502 windows are short.
503 Service Unavailable — The court portal is temporarily unavailable. The upstream system may be down for scheduled maintenance. The message field includes the affected court code. Retry after the indicated interval.
504 Gateway Timeout — The court portal did not respond within the request timeout. Some state court portals have high latency under load. Retry once; if the second attempt also times out, the upstream system is likely under stress.
Error Response Shape
All error responses return JSON with a consistent shape:
{
"error": {
"code": "COURT_NOT_COVERED",
"message": "Court 'txdc' exists but coverage is not active.",
"status": 422,
"request_id": "req_01hx..."
}
}The request_id field uniquely identifies the request. Include it when reporting issues — it allows DocketLayer support to trace the full request path including upstream court system responses.
Retry Strategy
Not all errors should be retried. Retryable errors: 429 (after Retry-After), 500, 502, 503, 504. Non-retryable without fixing the request: 400, 404, 422.
A 402 on a request that already included an x402-payment header requires diagnosing the rejection reason before retrying. A stale blockhash or expired signature requires rebuilding the payment. A replay attempt means the transaction was already consumed and cannot be reused.
Recommended backoff: first retry after 1 second, second retry after 4 seconds, third retry after 16 seconds. Do not retry more than three times without logging and alerting — persistent 5xx errors indicate an upstream issue that backoff will not resolve. For monitoring workloads that need to handle transient errors gracefully, see the efficient polling guide.