Errors

The API uses HTTP status codes to say what went wrong, and a JSON body with a detail field to say why.

Error format

Most errors carry a single message:

{ "detail": "Invalid API key" }

Validation errors carry a list, with one entry per invalid field:

{
  "detail": [
    {
      "type": "greater_than_equal",
      "loc": ["query", "limit"],
      "msg": "Input should be greater than or equal to 1",
      "input": "0",
      "ctx": { "ge": 1 }
    }
  ]
}

loc points at the field: where it was sent (query, path or body) followed by its path. Log detail as it comes, and branch on the status code and, for validation errors, on type and loc. Messages are meant for developers and can be reworded.

Status codes

Authentication failures

Every authentication failure is a 401, with a message that names the cause:

Authorization failures

A valid key without the endpoint's scope gets:

{ "detail": "Lack of permissions" }

with status 401, not 403. Check the scopes of the key with Retrieve key context, and see which scope each endpoint needs in Authentication. Scopes cannot be added to an existing key: create a new one.

Parameters are validated before scopes, so an invalid request made with the wrong key gets 422, not 401.

Validation errors

422 means a parameter or a body field does not match the schema: a missing required field, a value of the wrong type, a number out of range. The list in detail names every problem, so fix them all before retrying.

Two validation messages come from Vestta's own rules rather than the schema:

• Invalid phone in an inquiry — msg is Value error, El teléfono no es válido para el prefijo internacional seleccionado (Spanish, from the Vestta app) and loc names the phone field.
• Invalid phone in a rental lead — detail is a single string instead of a list: Invalid phone number. Use international format, e.g. +34600111222.

Handle detail as either a list or a string when you call the lead endpoints.

Resource not found

Retrieve a property returns 404 with Property not found when the property does not exist, is not public, is sold, rented or withdrawn, or belongs to another workspace.

Conflicts and rejected inquiries

Create an inquiry can fail after validation:

• 409 with Lead already exists — a lead with the same primary phone already exists in the workspace. The lead is already in Vestta: do not retry.
• 400 with Lead could not be created — the lead could not be stored for another data reason, such as a value longer than Vestta accepts.

Ingest a rental lead never returns 409: with a known phone it returns 200 and creates nothing.

Server errors

500 means the request could not be completed on Vestta's side. detail is a short message such as Error retrieving properties...; in rare cases the body is plain text, Internal Server Error.

• GET requests are safe to retry with exponential backoff.
• Retrying Ingest a rental lead is safe: a lead created by the first attempt makes the retry a no-op.
• Before retrying Create an inquiry, expect a 409 if the first attempt was stored.

A few 500s are caused by the request and will fail again on retry — for example, a non-numeric search.budget in a rental lead. See Troubleshooting.

There are no rate-limit errors: the API does not currently return 429.