> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nesu.pt/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Read structured problem responses and handle authentication, validation, quota, and lookup failures.

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

```json theme={null}
{
  "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](limits) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.