← Back to docs
Guides
GUIDEErrors and status codes
Error handling guide
This guide covers the status codes and error payloads your client should expect so implementation teams can build retries, user messaging, and operational alerts without guessing.
When to use it
Practical implementation contexts
Normalize API failures in your SDK or application client
Map validation failures to inline product errors
Differentiate retryable upstream problems from user-correctable request issues
Auth
Access model
Authentication
Applies to all authenticated and public routes. Some errors are raised directly by route validation and others come from shared middleware.
Failure cases to test in development
# Missing search query
curl https://api.entylink.com/v1/search \
-H "Authorization: Bearer etl_live_..."
# Invalid company number
curl https://api.entylink.com/v1/company/123 \
-H "Authorization: Bearer etl_live_..."
Parameters
ParameterTypeDescription
errorstringStable machine-readable error code
messagestringHuman-readable explanation of the failure
statusintegerHTTP status code repeated in the body
upgrade_urlstringIncluded only on `quota_exceeded` responses
Standard error envelope
Common 4xx and 5xx examplesReference
400 missing_query:
{
"error": "missing_query",
"message": "Query parameter 'q' is required",
"status": 400
}
401 unauthorized:
{
"error": "unauthorized",
"message": "Missing or invalid Authorization header. Use: Bearer <api_key_or_session>",
"status": 401
}
404 webhook_not_found:
{
"error": "webhook_not_found",
"message": "Webhook not found",
"status": 404
}
503 upstream_unavailable:
{
"error": "upstream_unavailable",
"message": "Companies House is currently unavailable",
"status": 503
}Related pages
Keep moving from docs into implementation and evaluation
Next step
Move from docs into a real registry workflow.
Entylink is built for teams embedding UK company data, verification, and monitoring into products rather than manually browsing the register.