Errors

When a request fails, use its HTTP status and structured problem body to decide what to do next. Error responses use Content-Type: application/problem+json.

Problem fields

Field	Type	Meaning
`type`	string	A problem identifier beginning with `https://api.nesu.pt/errors/`. Use this to distinguish errors with the same status.
`title`	string	A short description of the problem.
`status`	integer	The HTTP status code.
`detail`	string	An explanation of this failure.
`instance`	string	Your request path, including its query string when present.

Do not expect an error to use an endpoint’s success envelope. For example, a failed search returns a problem object, rather than a populated error field alongside data.

Validation errors

If you omit the search query or pass an invalid NIF to a company lookup, the problem includes an errors array. Each entry contains a field and a message. This example shows the response to an authenticated search without q:

{
  "type": "https://api.nesu.pt/errors/validation",
  "title": "Validation Failed",
  "status": 400,
  "detail": "The request contains invalid parameters.",
  "instance": "/api/v1/companies",
  "errors": [
    {
      "field": "q",
      "message": "is required"
    }
  ]
}

Error reference

The identifiers below are suffixes of the type URL.

HTTP status	Type suffix	Meaning and action
`400`	`validation`	Check the `errors` array and correct your query or NIF.
`401`	`unauthorized`	Supply a valid full API key in the bearer header. The response includes `WWW-Authenticate: Bearer`.
`404`	`company-not-found`	Your NIF is valid, but no company was found. Check the NIF.
`404`	`not-found`	Your request path is not registered. Check the base URL and endpoint.
`405`	`method-not-allowed`	Your HTTP method is not supported for this path. The documented endpoints use GET.
`429`	`rate-limit-exceeded`	Honor `Retry-After` and reduce your request rate.
`429`	`monthly-quota-exceeded`	Your included allowance and purchased credits are exhausted. Check usage, add credits, or wait for the reset.
`500`	`authentication-failed`	The server could not authenticate your key due to an internal failure. Retry later.
`500`	`search-failed`	The server could not search the directory. Retry later.
`500`	`internal-server-error`	The server could not complete your request. Retry later.
`502`	`company-lookup-failed`	Your company data could not be retrieved; upstream or local persistence failures can produce this response. Retry later.

An empty search result is a successful 200 response, not company-not-found.

Retry behavior

Correct validation and authentication failures before retrying. For temporary server errors, use a bounded retry policy with increasing delays. For 429, follow Limits and credits and distinguish rate exhaustion from credit exhaustion. An admitted company request may already have consumed a credit even if it returned an error. Each admitted retry consumes another credit.

Getting Started

Guides

Problem fields

Validation errors

Error reference

Retry behavior

​Problem fields

​Validation errors

​Error reference

​Retry behavior

Problem fields

Validation errors

Error reference

Retry behavior