---
updatedAt: 2026-06-18T00:19:18.000Z
agentTools:
  projectIndex: https://docs.pelcro.com/llms.txt
---

# Errors

How the Open API reports errors — HTTP status codes and the JSON error shapes.

The Open API uses conventional **HTTP status codes** to signal success or failure, and returns errors in a small, predictable set of JSON shapes. A `2xx` means success, a `4xx` means the request was rejected (something you can fix — bad input, auth, or a business rule), and a `5xx` means something went wrong on our side.

## Status codes

| Code                        | Meaning                                                                                                                |
| :-------------------------- | :--------------------------------------------------------------------------------------------------------------------- |
| `200 OK`                    | The request succeeded.                                                                                                 |
| `201 Created`               | A resource was created (e.g. a payment method or setup intent).                                                        |
| `204 No Content`            | The request succeeded with no response body (e.g. a delete).                                                           |
| `400 Bad Request`           | Validation failed, or a business rule rejected the request.                                                            |
| `401 Unauthorized`          | No authentication token was provided on a protected endpoint.                                                          |
| `403 Forbidden`             | The token is invalid, expired, or blacklisted.                                                                         |
| `404 Not Found`             | The resource does not exist — or a business rule rejected the request (several endpoints use `404` for domain errors). |
| `429 Too Many Requests`     | The request was throttled (e.g. repeated passwordless or login attempts).                                              |
| `500 Internal Server Error` | An unexpected error occurred on our side.                                                                              |

## Error response shapes

### Validation errors (`400`)

When one or more fields fail validation, the response contains an `errors` object keyed by field name, each with an array of messages:

```json
{
  "errors": {
    "plan_id": ["Plan ID is required"],
    "email": ["The email must be a valid email address."]
  }
}
```

### Application errors (`400` / `404`)

Business-rule rejections return a single `error` object with a `status` and a human-readable `message`:

```json
{
  "error": {
    "report_id": null,
    "status": 404,
    "message": "Invalid plan provided"
  }
}
```

### Authentication errors (`401` / `403`)

A protected endpoint called without a token returns `401`:

```json
{ "error": { "message": "Token not provided" } }
```

A token that is present but invalid, expired, or blacklisted returns `403`:

```json
{
  "error": {
    "status": 403,
    "message": "Authentication token is invalid, please try again"
  }
}
```

### Server errors (`500`)

Unexpected errors include a `report_id` you can quote to support so we can trace the incident:

```json
{
  "error": {
    "report_id": "9b2c1e7a-4f3d-6a2b-8c1d-0e5f7a9b3c2d",
    "status": 500,
    "message": "Sorry, something went wrong with your request. We are working to resolve this incident as quickly as possible."
  }
}
```

> 📘 Quoting `report_id`
>
> When you contact support about a `500`, include the `report_id` from the response — it lets us find the exact request in our logs.

> 🚧 Not-found bodies
>
> A few endpoints return an empty body alongside a `404` (e.g. a single resource that doesn't exist). Always branch on the status code, not on the presence of a body.

# Sibling pages

* [Overview](https://docs.pelcro.com/reference/api-open-intro.md)
* [Identification](https://docs.pelcro.com/reference/api-open-identification.md)
* [Resources](https://docs.pelcro.com/reference/api-open-resources.md)
* [How to integrate](https://docs.pelcro.com/reference/how-to-integrate.md)
* [Supported Languages](https://docs.pelcro.com/reference/api-open-supported-languages.md)
* [Site](https://docs.pelcro.com/reference/api-open-site.md)
* [Authentication](https://docs.pelcro.com/reference/api-open-authentication.md)
* [Password](https://docs.pelcro.com/reference/api-open-password.md)
* [Customer](https://docs.pelcro.com/reference/api-open-customer.md)
* [Subscription](https://docs.pelcro.com/reference/api-open-subscription.md)
* [Address](https://docs.pelcro.com/reference/api-open-address.md)
* [Payment methods](https://docs.pelcro.com/reference/api-open-payment-methods.md)
* [Payment](https://docs.pelcro.com/reference/api-open-payment.md)
* [Invoice](https://docs.pelcro.com/reference/api-open-invoice.md)
* [E-commerce](https://docs.pelcro.com/reference/api-open-ecommerce.md)
* [Newsletter](https://docs.pelcro.com/reference/api-open-newsletter.md)
* [Plan](https://docs.pelcro.com/reference/api-open-plan.md)
* [Memberships](https://docs.pelcro.com/reference/api-open-memberships.md)
* [Campaign](https://docs.pelcro.com/reference/campaign.md)
* [Bills](https://docs.pelcro.com/reference/api-open-bills.md)
* [Countries and states](https://docs.pelcro.com/reference/geo.md)
* [Visitor location](https://docs.pelcro.com/reference/api-open-location.md)
* [Source](https://docs.pelcro.com/reference/api-open-source.md)