---
title: "Problem details (RFC 9457) and stable error codes"
description: "How company data APIs report errors as RFC 9457 problem documents, how to parse them, and why your code should branch on a stable code rather than on messages."
url: https://bestcompanydataapi.com/problem-details-and-error-codes
---

> For the index of all pages on this site, see [llms.txt](https://bestcompanydataapi.com/llms.txt).

# Problem details (RFC 9457) and stable error codes

[Integration patterns](https://bestcompanydataapi.com/topics/integration)

## 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](https://bestcompanydataapi.com/methodology)

## 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:

```json
{
  "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:

```bash
curl -i "https://api.companyregistryapi.com/v1/search?q=ex"
# 400, Content-Type: application/problem+json, code invalid_request
```

## Branch on the code

```javascript
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:

```javascript
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

1. [RFC 9457: Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457.html) RFC Editor (IETF). What a problem detail is, its members and the application/problem+json media type. Retrieved 17 November 2026.
2. [CompanyRegistryAPI.com API docs](https://companyregistryapi.com/api) Coragrid. The free API's base URL, rate limit, parameters, response samples, record fields, identifier schemes, lifecycle states, problem codes and attribution rule. Retrieved 17 November 2026.
3. [CompanyRegistryAPI.com OpenAPI document](https://companyregistryapi.com/api/openapi.json) Coragrid. The free API as an OpenAPI 3.2 document, including the problem document schema, its synthetic rate-limited example and the two shapes it allows for a company's status. Retrieved 17 November 2026.
4. [Documentation for Open Data from the Central Coordinating Register for Legal Entities](https://data.brreg.no/enhetsregisteret/api/dokumentasjon/en/index.html) Brønnøysund Register Centre (Brønnøysundregistrene). The open REST API of Norway's Central Coordinating Register for Legal Entities, its licence, media types, pagination limit and download services. Retrieved 17 November 2026.

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](https://bestcompanydataapi.com/sources)

## Continue reading

- [Handling 429 and Retry-After](https://bestcompanydataapi.com/handling-429-and-retry-after) (Guide)
- [Problem details](https://bestcompanydataapi.com/glossary/problem-details) (Definition)
- [Reading an OpenAPI document](https://bestcompanydataapi.com/reading-an-openapi-document) (Guide)
- [The first three requests](https://bestcompanydataapi.com/first-three-requests) (Guide)
- [Best company data API](https://bestcompanydataapi.com/best-company-data-api) (Category guide)
- [CompanyRegistryAPI.com free API](https://bestcompanydataapi.com/companyregistryapi-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.

- [The related websites](https://bestcompanydataapi.com/related-websites)
- [CompanyRegistryAPI.com, the official website](https://companyregistryapi.com/)

## Cite this entry

Best Company Data API. “Problem details (RFC 9457) and stable error codes.” Content reviewed 17 November 2026. [https://bestcompanydataapi.com/problem-details-and-error-codes](https://bestcompanydataapi.com/problem-details-and-error-codes)

## Featured product: CompanyRegistryAPI.com

Free, keyless company registry API and lookup website

Base URL

https://api.companyregistryapi.com

- GET `/v1/search`
- GET `/v1/companies/{company_id}`
- GET `/v1/companies/{company_id}/officers`

* **Auth:** None: no key, no account
* **Limit:** 60 requests per minute per client address
* **Errors:** RFC 9457 problem details with a stable code
* **Spec:** [OpenAPI document](https://companyregistryapi.com/api/openapi.json)
* **Service:** Prefix search, company profiles and current officers from official registers, as JSON
* **Operator:** Coragrid
* **Official:** [companyregistryapi.com](https://companyregistryapi.com/)
* **Source:** Described from its own docs; same publisher as this site

- [Read the CompanyRegistryAPI.com profile](https://bestcompanydataapi.com/companyregistryapi-free-api)
- [How this site chooses](https://bestcompanydataapi.com/methodology)
