Last updated on October 23, 2026
Errors
Tell failures apart by error class and code, and know what to do about each one.
Every error
Every failure is an error you can catch by class. Every error carries code, message, status and the request id: requestId in TypeScript, request_id in Ruby and Python.
All of them extend one base class, so one check catches anything from Appnigma: SdkError in TypeScript, Appnigma::Error in Ruby, AppnigmaError in Python.
Quote the request id when you write to support@appnigma.ai. Never include your key or a token.
The classes
| TypeScript | Ruby | Python | When | Extra field |
|---|---|---|---|---|
SdkInputError | Appnigma::InputError | InputError | 400. A field is wrong or missing. Also raised before any call for a bad setting or a bad end customer id. | problems, a list of { field, problem } |
SdkAuthError | Appnigma::AuthError | AuthError | 401 or 403. The key is missing, unknown or cancelled, the microserver is not enabled, the platform is not switched on for you, or the connection lacks a scope an action needs. Also raised when a client starts with no key. | |
SdkNotFoundError | Appnigma::NotFoundError | NotFoundError | 404. No connection for that end customer on that platform, no such function, no such action, or no such record. When the function exists on another platform, details.platforms names it. | |
SdkReconnectError | Appnigma::ReconnectError | ReconnectError | 409 with CONNECTION_NEEDS_RECONNECT. The end customer has to approve again. | |
SdkNotAvailableError | Appnigma::NotAvailableError | NotAvailableError | Any other 409. The platform has no unified data for that yet; use request. | |
SdkRetiredError | Appnigma::RetiredError | RetiredError | 410 with FUNCTION_RETIRED. The function was live and was removed from your logic; it will not answer again. | |
SdkRateLimitError | Appnigma::RateLimitError | RateLimitError | 429, after the retries. Too many calls, or the platform asked us to slow down. | The wait in seconds, or empty when the server named none: retryAfterSeconds in TypeScript, retry_after_seconds in Ruby and Python |
SdkServerError | Appnigma::ServerError | ServerError | Any 5xx, after the retries. Also any answer that is not JSON. | |
SdkNetworkError | Appnigma::NetworkError | NetworkError | The API could not be reached, or an attempt ran out of time, after the retries. status and the request id are empty. | The underlying error: cause in TypeScript and Ruby, __cause__ in Python |
Catch by class
try {
await appnigma.post({ endCustomerId: "lawfirm-123", platform: "hubspot", object: "contact", record: {} });
} catch (error) {
if (error instanceof SdkInputError) {
for (const problem of error.problems) console.log(problem.field, problem.problem);
} else if (error instanceof SdkAuthError) {
console.log("check the key", error.code);
} else if (error instanceof SdkNotFoundError) {
console.log("this end customer is not connected yet");
} else if (error instanceof SdkReconnectError) {
console.log("ask the end customer to connect again");
} else if (error instanceof SdkRateLimitError) {
console.log("wait", error.retryAfterSeconds, "seconds");
} else if (error instanceof SdkServerError) {
console.log("our side failed, quote this id to support:", error.requestId);
} else if (error instanceof SdkNetworkError) {
console.log("could not reach the API", error.cause);
} else {
throw error;
}
}begin
client.post(end_customer_id: "lawfirm-123", platform: "hubspot", object: "contact", record: {})
rescue Appnigma::InputError => e
e.problems.each { |problem| puts "#{problem[:field]} #{problem[:problem]}" }
rescue Appnigma::AuthError => e
puts "check the key: #{e.code}"
rescue Appnigma::NotFoundError
puts "this end customer is not connected yet"
rescue Appnigma::ReconnectError
puts "ask the end customer to connect again"
rescue Appnigma::RateLimitError => e
puts "wait #{e.retry_after_seconds} seconds"
rescue Appnigma::ServerError => e
puts "our side failed, quote this id to support: #{e.request_id}"
rescue Appnigma::NetworkError => e
puts "could not reach the API: #{e.cause&.message}"
endfrom appnigma import (
AuthError,
InputError,
NetworkError,
NotFoundError,
RateLimitError,
ReconnectError,
ServerError,
)
try:
client.post(end_customer_id="lawfirm-123", platform="hubspot", object="contact", record={})
except InputError as error:
for problem in error.problems:
print(problem["field"], problem["problem"])
except AuthError as error:
print("check the key:", error.code)
except NotFoundError:
print("this end customer is not connected yet")
except ReconnectError:
print("ask the end customer to connect again")
except RateLimitError as error:
print(f"wait {error.retry_after_seconds} seconds")
except ServerError as error:
print("our side failed, quote this id to support:", error.request_id)
except NetworkError as error:
print("could not reach the API:", error.__cause__)Or catch the base class:
try {
await appnigma.connections.get({ endCustomerId: "nobody-here", platform: "hubspot" });
} catch (error) {
if (error instanceof SdkError) {
console.log(error.name, error.code, error.status, error.requestId);
} else {
throw error;
}
}begin
client.connections.get(end_customer_id: "nobody-here", platform: "hubspot")
rescue Appnigma::Error => e
puts "#{e.class} #{e.code} #{e.status} #{e.request_id}"
endfrom appnigma import AppnigmaError
try:
client.connections.get(end_customer_id="nobody-here", platform="hubspot")
except AppnigmaError as error:
print(type(error).__name__, error.code, error.status, error.request_id)Every code
code is one of the codes below, or whatever a newer server sent. A code your version of the SDK does not know is kept as it is, never replaced. The full list is in SDK_ERROR_CODES in TypeScript, Appnigma::ERROR_CODES in Ruby and appnigma.ERROR_CODES in Python.
| Status | Code | When | What to do |
|---|---|---|---|
| 400 | INVALID_INPUT | A field is wrong, missing or unknown. problems lists each one. | Fix the fields it names. |
| 401 | SDK_KEY_MISSING | No key was sent. | Set APPNIGMA_SDK_KEY, or pass the key. |
| 401 | SDK_KEY_INVALID | The key is unknown. | Check the key. Ask Appnigma for a new one if needed. |
| 401 | SDK_KEY_CANCELLED | The key was cancelled. | Ask Appnigma for a new key. |
| 403 | MICROSERVER_NOT_ENABLED | Your company has no active microserver. | Contact Appnigma. |
| 403 | PLATFORM_NOT_ENABLED | The platform is not switched on for your company. | Ask Appnigma to switch it on. |
| 403 | MISSING_SCOPES | The end customer's connection was not given a scope an action needs. details.missing names them. | The connection needs those scopes before the action can run. |
| 404 | END_CUSTOMER_NOT_FOUND | No connection for that end customer on that platform. | Connect the end customer. |
| 404 | FUNCTION_NOT_FOUND | No function with that platform and name. details.platforms names another platform that has it. | Check the name and platform with catalog. |
| 404 | ACTION_NOT_FOUND | The platform has no action with that name. | Check the name with actions.list. |
| 404 | RECORD_NOT_FOUND | No record with that id. | Check the id. |
| 409 | CONNECTION_NEEDS_RECONNECT | The end customer has to approve again. | Send them a new connect link. |
| 409 | DATA_TYPE_NOT_AVAILABLE | The platform has no unified data for that yet. | Use request. |
| 410 | FUNCTION_RETIRED | The function was live and was removed from your logic. details name the function and when it was retired. | Stop calling it. Check what is live with catalog. |
| 429 | RATE_LIMITED | Too many calls with this key. | Wait as long as the error says, then try again. |
| 429 | PLATFORM_RATE_LIMITED | The platform asked us to slow down. | Wait as long as the error says, then try again. |
| 502 | PLATFORM_ERROR | The platform refused the call. message carries its reason. | Read the message. |
| 504 | TIMED_OUT | The function did not answer in time. | Decide whether to call again. |
| 500 | LOGIC_FAILED | The function failed. No inner detail is returned. | Quote the request id to support. |
| 500 | INTERNAL_ERROR | Something went wrong on Appnigma's side. | Quote the request id to support. |