API and SMTP errors: when to contact support

An approval is complete, but the expected information has not appeared on the card. Or a customer is still waiting for a confirmation email. You have found a message, but need to understand what it tells you and who can help keep the process moving.

By the end of this article, you will be able to recognize the main error categories, choose a useful check and collect the context needed to ask for help. You do not need programming or email server administration experience to make that first decision.

📖 What you will understand here:

Start with the action and the source of the message

Before interpreting a code, describe what should have happened: updating a field, creating a request or sending a confirmation. Then identify where you saw the message and which service produced it.

An API lets systems exchange information. A routine might retrieve data from Pipefy and send an update to another application. The message displayed by the integration tool may have come from that other service.

SMTP is a protocol used to send email. Here, the useful question is where the communication was rejected: during connection, authentication or message processing.

Consider a Procurement routine: approval is complete in the finance system, but the card is still waiting for an update. Identifying the call that should update the card helps you focus on the relevant part of the process.

If you work with flows in Pipefy Integrations, the guide to diagnosing integration executions, in Portuguese, explains how to locate the step and its records. These records, also called logs, contain information about what ran.

API: separate the response from the operation result

The HTTP status is the code associated with a call's response. The response body contains the data and details returned by the service. Read them together.

In Pipefy's GraphQL API, HTTP 200 can accompany an operation error. Check errors and the returned result. Some operations also provide a success indicator, which may be false.

Use these categories to choose an initial check:

1. Authentication: signals such as 401 or UNAUTHORIZED call for checking the identity used in the request. A credential provides that identification. The integration owner should verify its validity and format.
2. Permission: INVALID_ROLE or PERMISSION_DENIED point toward access required for the action or resource. Identifying an account and allowing an action are separate checks.
3. Data or resource: INVALID_INPUT suggests reviewing the submitted values. RESOURCE_NOT_FOUND calls for checking the resource identifier and context.
4. Limit: 429 indicates request rate limiting. With USAGE_LIMIT_EXCEEDED, read the operation context, including whether it involves sending email. Identify the relevant limit before choosing a correction.

In the Procurement example, suppose the call returns HTTP 200 with INVALID_INPUT. The next useful check is to compare the submitted value with the expected format. Replacing the credential does not address that signal.

If the message mentions query complexity or execution time, the technical owner can consult the API limits and best practices. These constraints differ from the number of requests.

• Learn more: Pipefy's status codes and error handling reference explains response codes. For authentication, use the current Unauthorized guidance.

SMTP: distinguish connection, authentication and delivery

A connection can be established without the email reaching its destination. Interpret the message in relation to the stage where it appeared.

Unreachable host or timeout: communication did not complete. The host is the server address; a timeout means the waiting period ended. IT can check the address, port, network and service availability.

Authentication rejected: the service did not accept the identity or authentication method. SMTP code 535 points to this category; 530 means the action requires authentication. An admin should check which method is authorized for that connection.

TLS or certificate error: this concerns the secure connection. Send the context to IT without disabling protections to complete the send.

SMTP 4xx or 5xx response: in SMTP, 4xx indicates a temporary rejection; 5xx calls for a correction or review before repeating the same attempt. Read the full message too. The protocol category alone does not establish how Pipefy will retry.

For example, a customer confirmation has not arrived and the connection shows an authentication warning. Start with the person who administers the connection. Editing the email body or changing its recipient does not address the hypothesis suggested by that warning.

The update on custom SMTP error notifications helps you recognize when a connection needs attention. If it indicates that authentication must be renewed, involve the responsible admin.

• Learn more: the Help Center covers custom email configuration through SMTP and connecting Microsoft with OAuth 2.0. Follow the guidance that applies to the connection your company administers.

Choose the next check and who can help

You can confirm the expected action, message, time and scope. Investigating credentials, access, data or policies may require other people:

1. Integration owner: checks the submitted data, request destination and expected result.
2. Admin or IT: checks access, authentication, network and email service policies.
3. Pipefy Support: helps when platform behavior needs investigation or the cause remains unclear. More than one team may be involved.

If the message mentions an HTTP 5xx code or a timeout, record the service involved and whether it happens repeatedly. Before running an update or sending an email again, check whether the intended result already occurred. An incomplete response is not enough evidence to repeat the entire routine.

Gather the context needed to investigate

A useful summary connects the event to its impact on work. Use these prompts without including passwords or credentials:

1. Expected and observed: what should have happened and what actually happened.
2. Time and scope: date, time, time zone, frequency and the number of affected cases you know about.
3. Technical context: step, service, full message and available code. Include the relevant card, pipe or execution ID and correlation_id, if the response contains it.
4. Checks and impact: recent changes, what has already been reviewed and which activity is waiting to continue.

For an API investigation, the owner can add a minimal example of the submitted data with sensitive information hidden. For email, provide the affected sender, provider and message reference, when available, through a private channel.

Choose a real occurrence and complete the summary. Connecting the message, action and context gives you a clearer hypothesis for the next check or a support request that helps the investigation begin.

Before moving on, confirm that you understand:

☐ The message may appear somewhere other than the service that produced it.

☐ HTTP 200 does not guarantee operation success in Pipefy's GraphQL API.

☐ Email connection, authentication and delivery are separate stages.

☐ You can gather context and ask for help without sharing credentials.