Problem details (RFC 9457) and stable error codes
Answer in brief
RFC 9457 problem details give HTTP APIs one JSON error format, served as application/problem+json, with members such as type, title, status and detail. A company data API that adds a stable code member lets your code branch on the code, log the request ID and show the detail, instead of parsing human-readable messages.
Disclosure. This site is published by Coragrid, the operator of CompanyRegistryAPI.com, and promotes it. “Best” is our editorial choice, not a measured ranking. Other products are described only from their own official pages. How we choose
What RFC 9457 defines
RFC 9457 defines a “problem detail” to carry machine-readable details of
errors in HTTP responses, so APIs do not each invent an error format. Its JSON
form is served as application/problem+json and has five standard members:
| Member | Meaning |
|---|---|
type |
A URI that identifies the problem type |
title |
A short, human-readable summary of the type |
status |
The HTTP status code |
detail |
An explanation specific to this occurrence |
instance |
A URI that identifies this occurrence |
APIs may add their own members. That is where stable codes live.
The shape in practice
The free CompanyRegistryAPI.com API returns problem documents with a stable
code. Its OpenAPI document adds request_id and retryable to the standard
members and gives this synthetic example; live 400, 404 and 503
responses on 17 November 2026 carried the same members:
{
"type": "https://companyregistryapi.com/problems/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "The free API allows a bounded number of requests per minute per client; retry after 1 seconds.",
"instance": "https://api.companyregistryapi.com/v1/search",
"request_id": "req_014d2pf2dbsqqg28t5cy4tqkff",
"code": "rate_limited",
"retryable": true
}
You can see a real one yourself with an invalid request:
curl -i "https://api.companyregistryapi.com/v1/search?q=ex"
# 400, Content-Type: application/problem+json, code invalid_request
Branch on the code
async function call(url) {
const response = await fetch(url);
const type = response.headers.get("Content-Type") ?? "";
if (response.ok) return response.json();
if (!type.startsWith("application/problem+json")) {
throw new Error(`HTTP ${response.status}`);
}
const problem = await response.json();
switch (problem.code) {
case "invalid_request":
throw new Error(`Fix the request: ${problem.detail}`);
case "not_found":
return null; // no company is visible under that ID
case "rate_limited":
case "upstream_busy":
case "upstream_unavailable":
case "upstream_error":
throw Object.assign(new Error(problem.title), { retry: true, problem });
default:
throw Object.assign(new Error(problem.title), { problem });
}
}
Unknown codes fall through to a generic error, so a code the provider adds later does not crash the client.
The documented codes
| Code | Status | Meaning, from the docs |
|---|---|---|
invalid_request |
400 |
A parameter is missing or malformed; detail names it |
not_found |
404 |
No company is visible under that ID |
rate_limited |
429 |
Retry after the seconds in Retry-After |
upstream_error |
502 |
The company data service rejected the request; retryable |
upstream_busy |
503 |
Busy; retry after the seconds in Retry-After |
upstream_unavailable |
503 |
Temporarily unavailable; retryable |
Not every API uses problem details
The Brønnøysund Register Centre’s open data API documents its own error body,
with members such as timestamp, status, error and path, served as
application/json. Check the error section of each API you integrate and
normalise the shapes in one place, so the rest of your code sees one error
type.
Log the request ID
When an error reaches support, the request ID lets the provider find the call.
CompanyRegistryAPI.com’s support page asks you to include the API request and,
for a company, its permanent ID. Log request_id, the path and the code
together:
console.error(JSON.stringify({
code: problem.code,
status: problem.status,
request_id: problem.request_id,
instance: problem.instance,
}));
Questions and answers
Should my code branch on the HTTP status or on the code?
On the code. Several codes share a status, such as upstream_busy and upstream_unavailable, which are both 503, and only the code tells them apart.
Can I show the detail text to users?
Show it to developers and in logs. For end users, map the code to your own message, because detail is written for the person fixing the request.
What is RFC 7807?
The earlier version of problem details. RFC 9457 obsoletes it and keeps the same media type, so a client written for one works with the other.
Sources for this entry
- RFC 9457: Problem Details for HTTP APIs
- CompanyRegistryAPI.com API docs
- CompanyRegistryAPI.com OpenAPI document
- Documentation for Open Data from the Central Coordinating Register for Legal Entities
Each source supports only what its publisher says about its own product or data. Official descriptions do not establish comparative performance, and this site has run no benchmark. All sources
Continue reading
- Handling 429 and Retry-After (Guide)
- Problem details (Definition)
- Reading an OpenAPI document (Guide)
- The first three requests (Guide)
- Best company data API (Category guide)
- CompanyRegistryAPI.com free API (Profile)
How the related websites connect
This is one of 3 coordinated reference sites published by Coragrid. They cover neighbouring questions and feature the same product, so they are not independent endorsements of it or of each other.
Cite this entry
Best Company Data API. “Problem details (RFC 9457) and stable error codes.” Content reviewed . https://bestcompanydataapi.com/problem-details-and-error-codes