Errors and Support

The Platica API uses standard HTTP status codes to indicate whether a request succeeded or failed. This section describes the error formats, common codes, and how to get help.

Error Format

Every error response follows a consistent JSON format:

{
  "code": 404,
  "error": "Not Found - El recurso no existe",
  "details": "Agent not found"
}

Field	Type	Description
`code`	number	HTTP status code
`error`	string	Descriptive error message
`details`	string \| object \| array	Additional context. Validation errors identify rejected fields here

Common Error Codes

Code	Status	Description
`400`	Bad Request	The request has validation errors or an incorrect format
`401`	Unauthorized	API Key or OAuth token invalid, expired, revoked, or missing
`402`	Payment Required	The workspace reached its credit limit
`403`	Forbidden	You do not have permission for this resource, or the OAuth token is missing the `platica:write` scope
`404`	Not Found	The requested resource does not exist
`409`	Conflict	The resource changed or is busy, such as a conversation processing another turn
`410`	Gone	The resource is no longer available
`422`	Unprocessable Entity	The request is valid but could not be processed
`429`	Too Many Requests	You have exceeded the request limit
`500`	Internal Server Error	Internal server error
`502`	Bad Gateway	An internal service or provider could not complete the request
`503`	Service Unavailable	Service temporarily unavailable
`504`	Gateway Timeout	An internal service did not finish before the time limit

400 - Bad Request:

{
  "code": 400,
  "error": "Bad Request - Validation error",
  "details": "El campo 'name' es requerido"
}

401 - Unauthorized:

{
  "code": 401,
  "error": "Unauthorized - Invalid API key",
  "details": "La API key proporcionada no es válida"
}

On /mcp and on calls with an expired pl_at_…, the 401 also carries WWW-Authenticate with resource_metadata so the MCP client can start OAuth. See MCP Authentication .

403 - Forbidden:

{
  "code": 403,
  "error": "Forbidden - Access denied",
  "details": "No tienes permisos para acceder a este workspace"
}

If the OAuth access token is read-only, the 403 uses error: "insufficient_scope" and asks for platica:write in the challenge. That is not a role permission: the client must re-authorize.

404 - Not Found:

{
  "code": 404,
  "error": "Not Found - Resource not found",
  "details": "Agent not found"
}

429 - Too Many Requests:

{
  "code": 429,
  "error": "Too Many Requests - Rate limit exceeded",
  "details": "Has excedido el límite de 30 peticiones por segundo"
}

Validation Errors

When several fields fail validation, details is an array. Each item identifies the path and failed rule:

{
  "code": 400,
  "error": "Bad Request - The request has validation errors",
  "details": [
    {
      "path": ["attachments"],
      "message": "Array must contain at most 10 element(s)"
    }
  ]
}

In POST /v1/chat, delay and scheduleAt are mutually exclusive. Sending both returns 400 and identifies the fields in details.

Correct every item in details before retrying the request.

Rate Limiting

The API enforces request limits to guarantee a stable service for everyone.

Limit	Value
Requests per second	30 per API key

Consejo

If you need higher limits for your integration, contact the team at integraciones@platica.mx to evaluate your case.

Rate Limiting Headers

Responses include headers that help you monitor your usage:

Header	Description
`X-RateLimit-Limit`	Maximum number of requests allowed
`X-RateLimit-Remaining`	Remaining requests in the current window
`X-RateLimit-Reset`	Timestamp when the limit resets

Advertencia

When you get a 429 error, wait for the time indicated in X-RateLimit-Reset before retrying. Implementing exponential backoff is a good practice.

Best Practices

To handle errors effectively:

Always check the status code before processing the response
Implement retries with exponential backoff for 502, 503, and 504
Do not retry 4xx errors without correcting the request
Monitor the rate limiting headers to avoid exceeding limits
Log errors with the details field for debugging

Advertencia

Before retrying a 502 or 504 from a synchronous endpoint, fetch the resource: the operation may have completed even if the HTTP connection failed. A 409 caused by a busy conversation can be retried with backoff.

Technical Support

If you need help with your integration or have questions:

Channel	Contact
Integrations and API	integraciones@platica.mx
General Support	soporte@platica.mx

Nota

For faster resolution, include in your request: the endpoint used, the request body, the response received, and your API key (only the last 4 characters for security).

Previous Delete Webhook